Doc/Developing.hs: add some information about Haddock documentation.

darcs-hash:20071219215300-bd4d7-ddf6e83d3e73cbfb22cdf96f0080763a13288199.gz

1 files changed, 26 insertions, 1 deletions

diff --git a/XMonad/Doc/Developing.hs b/XMonad/Doc/Developing.hs
index ced3175..9235a95 100644
--- a/XMonad/Doc/Developing.hs
+++ b/XMonad/Doc/Developing.hs
@@ -246,7 +246,7 @@ xmonad contributed extensions.
 * Comment every top level function (particularly exported funtions), and
   provide a type signature.
 
-* Use Haddock syntax in the comments.
+* Use Haddock syntax in the comments (see below).
 
 * Follow the coding style of the other modules.
 
@@ -260,6 +260,31 @@ xmonad contributed extensions.
 * Any pure function added to the core should have QuickCheck properties
   precisely defining its behaviour.
 
+For examples of Haddock documentation syntax, have a look at other
+extensions.  Important points are:
+
+* Every exported function (or even better, every function) should have
+  a Haddock comment explaining what it does.
+
+* Literal chunks of code can be written in comments using
+  \"birdtrack\" notation (a greater-than symbol at the beginning of
+  each line).  Be sure to leave a blank line before and after each
+  birdtrack-quoted section.
+
+* Link to functions by surrounding the names in single quotes, modules
+  in double quotes.
+
+* Literal quote marks and slashes should be escaped with a backslash.
+
+To generate and view the Haddock documentation for your extension, run
+
+> runhaskell Setup haddock
+
+and then point your browser to @\/path\/to\/XMonadContrib\/dist\/doc\/html\/xmonad-contrib\/index.html@.
+
+For more information, see the Haddock documentation:
+<http://www.haskell.org/haddock/haddock-html-0.8/index.html>.
+
 -}
 
 {- $license