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@. * 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 guidehttp://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