[xmonad] xmonad-contrib, Haddock, and You!

[Brent Yorgey]

Hi all!

In order to help encourage good documentation, I just pushed a patch to
xmonad-contrib to include haddock generation in the automatic darcs test. In
other words, the haddock documentation must build without errors in order to
record a patch.  To ease the pain a bit, here's a quick summary of Things
You Should Know about haddock documentation for contributed extension
modules:

* all exported functions in contributed modules should have a haddock-style
comment saying what they do.  Haddock-style comments look like this:
-- | This is a haddock-style comment
Note the vertical pipe character (and the spaces around it!).

* You can quote literal code blocks by using "birdtracks", like this:

> foo x = x + h
>     where h = 3

Be sure to leave blank lines both before and after any such code blocks!  It
won't parse correctly without the blank lines.

* Inline literal code fragments can be surrounded by @at symbols at .

* To include a hyperlink to another function in the module, surround the
function name in 'single quotes'.  To link to another module, surround the
module name in "double quotes".

* To include literal single or double quotes, frontslashes, backslashes, at
symbols, etc., escape them with backslashes, \"like this\".  Not escaping
things like this is another common reason your documentation might fail to
compile.

For more detail, you should have a look at the Haddock user
guide<http://www.haskell.org/haddock/haddock-html-0.8/index.html>.
And of course, the best advice overall is to just look at the style of other
extensions, and emulate it.

Happy hacking!
-Brent
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/xmonad/attachments/20071219/46b4a72d/attachment-0001.htm