May 2002 - HaskellDoc

ANNOUNCE: Haddock version 0.2, a Haskell documentation tool
by Simon Marlow 21 May '02

21 May '02

I'm pleased to announce version 0.2 of Haddock, a documentation generation tool for Haskell source code. It's available from http://www.haskell.org/haddock/ The changes relative to version 0.1 are listed here: http://www.haskell.org/haddock/CHANGES.txt Cheers, Simon

3 2

RE: ANNOUNCE: Haddock version 0.2, a Haskell documentation tool
by Simon Marlow 13 May '02

13 May '02

> Just two remarks: > > * The layout of documented constructors and record fields is a bit > heavyweight IMHO, almost a screenfull of lines for common constructs. > I understand the current rationale, but nevertheless, does anybody > have nice ideas for producing the more common "tabular" layout found > in so many source files like: > > data Blah = -- The Blah type does blah blah blah... > Foo Int -- Comment for Foo > | Bar Float -- Comment for Blah Yes, this is one thing that could definitely be improved. However, you probably wouldn't want this kind of layout all the time - for example when the comments were particularly long the currently layout mgiht be more appropriate (IMHO). Should it be possible to specify attributes for declarations too, something like -- #tabular -- | doc for the 'Blah' type data Blah = Foo Int -- | doc for 'Foo' | ... or maybe it should switch to the tabular form automatically when the comments are "small enough"? There are one or two heuristics like this already: eg. when there's no documentation on any of the constructors we switch to a more compact rendering of the declaration. > * Having doc strings for function arguments would be high on my > personal wishlist. I know it's already in the TODO, and after > trying to implement it for myself and getting myriads of S/R > conflicts, I probably understand why it's still there... :-] > The former remark would hold for this type of documentation, > too, BTW. Ok, I'll have a think about how best to do this. Any thoughts on what the rendering should look like? I'd considered something like this: foo :: <doc for the 'foo' function> A <doc for the A argument> -> B <doc for the B argument> -> R <doc for the return value> or maybe the type should be given twice, like: foo :: A -> B -> R <doc for the 'foo' function> A <doc for the A argument> -> B <doc for the B argument> -> R <doc for the return value> Anyway, thanks for the comments. Cheers, Simon

2 1

RE: Feature request for Haddock: cross-module name reference
by Simon Marlow 13 May '02

13 May '02

> Another little wish for Haddock: It is currently possible to reference > names in scope via 'foo' and modules via "bar.baz.blah". But sometimes > it would be convenient to reference a name in another module without > importing it just for documentation purposes. Further note that > circularity in documentation is not uncommon. So a markup for this > task would be very nice. I'm not sure if the name should always be > rendered in a fully qualified way, because this tends to clutter up > the documentation. On the other hand it would be better in printed > (i.e. non-mouse-clickable) docs. Hmmm... > > Does this make sense? Actually I already had this on the TODO list (perhaps not committed). The idea I had was that if you write 'Foo.bar' and Foo.bar isn't otherwise in scope, then Haddock just trusts you and links straight to Foo.html#bar. There's probably no need to fully qualify the name in the rendered HTML, since the hyperlink will point to the right place. The only situation in which this wouldn't work is if there's a different Foo.bar in scope (not the one you wanted). But I imagine this is pretty rare... Cheers, Simon

1 0

Feature request for Haddock: cross-module name reference
by Sven Panne 13 May '02

13 May '02

Another little wish for Haddock: It is currently possible to reference names in scope via 'foo' and modules via "bar.baz.blah". But sometimes it would be convenient to reference a name in another module without importing it just for documentation purposes. Further note that circularity in documentation is not uncommon. So a markup for this task would be very nice. I'm not sure if the name should always be rendered in a fully qualified way, because this tends to clutter up the documentation. On the other hand it would be better in printed (i.e. non-mouse-clickable) docs. Hmmm... Does this make sense? Cheers, S.

1 0

RE: ANNOUNCE: Haddock version 0.2, a Haskell documentation tool
by Sven Panne 13 May '02

13 May '02

Simon Marlow wrote: > [...] when the comments were particularly long the currently layout > mgiht be more appropriate (IMHO). Well, I didn't suppose forcing everything on a single line. Automatically wrapped paragraphs are more suitable: data Blah = < The Blah type does blah blah blah blah blah blah and is very well suited for blah blah blah... > Foo Int < short comment for Foo> | Bar Float < a little bit longer comment for Blah, which extends over two lines... > > Should it be possible to specify attributes for declarations too, > something like > > -- #tabular > -- | doc for the 'Blah' type > data Blah > = Foo Int -- | doc for 'Foo' > | ... > > or maybe it should switch to the tabular form automatically when the > comments are "small enough"? Hmmm, probably a command-line option plus directives for explicitly deviating from the specified default would do the job. > [ Rendering function argument documentation ] I'd prefer the first version, redundancy is evil IMHO. Cheers, S.

1 0

Re: ANNOUNCE: Haddock version 0.2, a Haskell documentation tool
by Ashley Yakeley 10 May '02

10 May '02

It would be nice if it would report instance declarations... -- Ashley Yakeley, Seattle WA

1 0

Re: ANNOUNCE: Haddock version 0.2, a Haskell documentation tool
by Ashley Yakeley 09 May '02

09 May '02

At 2002-05-09 09:44, Simon Marlow wrote: >I'm pleased to announce version 0.2 of Haddock, a documentation >generation tool for Haskell source code. It's available from > > http://www.haskell.org/haddock/ It's at <http://www.haskell.org/haddock/haddock-0.2-src.tar.gz>. -- Ashley Yakeley, Seattle WA

1 0

RE: Haddock Parse Bugs
by Simon Marlow 06 May '02

06 May '02

> I tried using Haddock on JVM-Bridge. It fails on empty datatypes: > > module HDTest where > { > data Foo; > } Fixed, thanks. > It also fails on 'with' (for implicit parameters). 'with' is > deprecated > in 5.03, but its replacement syntax using 'let' won't work > with 5.02.2. There isn't any support for implicit parameters in the parser yet, I've added it to the TODO list for now. Cheers, Simon

1 0

Re: Using Haddock for standard libraries (was: RE: ANNOUNCE: Haddock version 0.1, a Haskell documentation tool)
by Ashley Yakeley 06 May '02

06 May '02

At 2002-05-06 03:27, Simon Marlow wrote: >This doesn't mean it will be a "standard" as such, merely that the >reference implementation of the libraries will be marked-up using >Haddock annotations. If people aren't comfortable with requiring a >specific tool for generating the documentation from the reference >sources, then we could perhaps standardise the annotation syntax >instead. That's probably good enough for me. I'd like to start documenting my code, but I'd like to be sure that I won't have to rewrite all the comments just because the doc tool falls out of favour. -- Ashley Yakeley, Seattle WA

1 0

Using Haddock for standard libraries (was: RE: ANNOUNCE: Haddock version 0.1, a Haskell documentation tool)
by Simon Marlow 06 May '02

06 May '02

[ redirected to libraries(a)haskell.org ] > At 2002-05-01 04:48, Simon Marlow wrote: > > >I'm pleased to announce version 0.1 of Haddock, a documentation > >generation tool for Haskell source code. > > I take it this is the "standard" Haskell documentation tool now, that > implementations of the standard libraries will use? I've been > waiting for something like this. I'd like Haddock to become a widely-used Haskell documentation tool, but I don't want to presume to call it "the standard tool". I'd like us to use Haddock to document the hierarchical libraries in fptools/libraries (indeed, that was the main reason I wrote it). Haddock is by no means perfect, but I think it's a step in the right direction. What do other people think? Should we adopt Haddock as the tool for documenting the libraries? This doesn't mean it will be a "standard" as such, merely that the reference implementation of the libraries will be marked-up using Haddock annotations. If people aren't comfortable with requiring a specific tool for generating the documentation from the reference sources, then we could perhaps standardise the annotation syntax instead. Nevertheless, we do *need* to document fptools/libraries in order that we (the GHC team) can release the next version of GHC. So excessive faffing around is not an option :-) Assuming that we adopt Haddock, I'd be grateful for any volunteers to help document everything in fptools/libraries - including the Prelude and Haskell 98 standard libraries (one of the shortcomings of our current library documentation is that one has to go elsewhere to find the documentation for these standard bits). Prelude & std library documentation can for the most part be culled from the Reports and various other resources on the web, and much of the other library documentation can be ported from the old hslibs documentation, suitably unDocBooked. I'll volunteer to coordinate the documentation effort. Cheers, Simon

1 0