Excerpts from Adam Megacz's message of Sun Apr 24 22:54:55 -0400 2011:
> Okay, perhaps this isn't the best use of my time.
I mean, alternative representations for the code can come in handy.
As you yourself demonstrate, people don't necessarily naturally
go for the source, and hyperlinks are a very nice thing.
Haddock, unfortunately, was intended as API documentation tool,
and not a code documentation tool, and this shows in a number of
places:
- Modules that are not exported by the package are hidden,
but since they're used internally you would like to see
docs about them.
- Many of GHC's modules are written in literate style,
which Haddock doesn't really have first-class support for.
- Most of us work on GHC HEAD, and since's generating Haddock
docs adds a hefty bit of time to the compilation process,
I usually don't bother. As a corallary, it's easy to
write a comment and eyeball that it looks good, but harder
to write a comment and make sure it looks good in Haddock.
My personal experience (in other projects [1]) is that you need
to be continually looking at your generated documentation.
Cheers,
Edward
[1] http://blog.ezyang.com/2010/06/secret-of-autogenerated-docs/
_______________________________________________
Cvs-ghc mailing list
[email protected]
http://www.haskell.org/mailman/listinfo/cvs-ghc
