Hello. Simon Marlow wrote:
I don't think that's entirely fair. Most of the libraries that come with GHC (and Hugs, and soon Nhc) are documented. See for example
As far as I know (please correct me, if I err) one shortcoming of Haddock is its restriction to .hs-files. I think there are a lot of real literate programmers out there which would prefer a Haskell documentation tool for their literate Haskell scripts. Therefore I present the tool lhs2hs, which may seem very puristic and errorprone at this time (in fact it is). It transforms a .lhs-file into a .hs file. Furthermore tex-comments are used to pass information to e.g. Haddock: Example: %%Haddock:this function... %%Haddock:...
testfun...
%%Haddock:another function... \begin{code} ... \end{code} This .lhs file becomes transformed to {-| this function... ... -} testfun... {-| another function... -} ... Ok, its simple, but it can be useful and it is extensible! I have attached the very first version. Type: ghc --make Main.lhs -package util -o lhs2hs ./lhs2hs -h Main.lhs haddock -h Main.hs latex Main.lhs Another idea to simplify literate programming with Haskell: allow XML (introduce a new file extension .xhs), e.g.: <hscomment describes="quicksort"> sorts a list </hscomment> <hsdecl defines "quicksort"> quicksort... </hsdecl> This would allow more transformations! Bye, Steffen
On Wednesday 23 April 2003 10:41 am, Steffen Mazanek wrote:
Hello.
Simon Marlow wrote:
I don't think that's entirely fair. Most of the libraries that come with GHC (and Hugs, and soon Nhc) are documented. See for example
As far as I know (please correct me, if I err) one shortcoming of Haddock is its restriction to .hs-files.
This seems like a good way of transitioning from .lhs to haddock'd .hs. In the long run, I think we (meaning Simon :-) should to extend haddock to take the place of the .lhs style of documenting code. I use haddock to document interfaces for modules and it works wonderfully for that (and it would be even better if I could use haddock comments inside records and in between constructor arguments, hint, hint). But I find myself using it in comments within code (especially within local functions) too. Perhaps a haddock that had two modes (one for interfaces, one for implementation) would work. The interface mode would work as it does now. The implementation mode would produce a .html version of the entire module, using haddock comments to mark it up. Simon: how much work would this be? A -- Andy Moran Ph. (503) 526 3472 Galois Connections Inc. Fax. (503) 350 0833 3875 SW Hall Blvd. http://www.galois.com Beaverton, OR 97005 moran@galois.com
Andy Moran wrote:
I use haddock to document interfaces for modules and it works wonderfully for that (and it would be even better if I could use haddock comments inside records and in between constructor arguments, hint, hint).
But I find myself using it in comments within code (especially within local functions) too. Perhaps a haddock that had two modes (one for interfaces, one for implementation) would work. The interface mode would work as it does now. The implementation mode would produce a .html version of the entire module, using haddock comments to mark it up.
I would find this very useful too, even without fancy syntax highlighting and crossreferences for the code (although they would of course be nice!). --KW 8-) -- Keith Wansbrough <kw217@cl.cam.ac.uk> http://www.cl.cam.ac.uk/users/kw217/ University of Cambridge Computer Laboratory.
participants (3)
-
Andy Moran -
Keith Wansbrough -
Steffen Mazanek