From 1e21c673a42d3337e05607ed4f47024c65d0cc9d Mon Sep 17 00:00:00 2001 From: Mateusz Kowalczyk Date: Sun, 9 Feb 2014 17:51:22 +0000 Subject: Document module header. Fixes Haddock Trac #270. --- doc/haddock.xml | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 62 insertions(+), 8 deletions(-) diff --git a/doc/haddock.xml b/doc/haddock.xml index b5331c26..7c1ca91c 100644 --- a/doc/haddock.xml +++ b/doc/haddock.xml @@ -100,7 +100,7 @@ We might want documentation in multiple formats - online and printed, for example. Haddock comes with HTML, LaTeX, and Hoogle backends, and it is structured in such a way that adding new - back-ends is straightforward. + backends is straightforward. @@ -1229,17 +1229,71 @@ f :: Int -- ^ The 'Int' argument
The module description - A module may contain a documentation comment before the - module header, in which case this comment is interpreted by - Haddock as an overall description of the module itself, and - placed in a section entitled Description in the - documentation for the module. For example: + A module itself may be documented with multiple fields + that can then be displayed by the backend. In particular, the + HTML backend displays all the fields it currently knows + about. We first show the most complete module documentation + example and then talk about the fields. --- | This is the description for module "Foo" -module Foo where +{-| +Module : W +Description : Short description +Copyright : (c) Some Guy, 2013 + Someone Else, 2014 +License : GPL-3 +Maintainer : sample@email.com +Stability : experimental +Portability : POSIX + +Here is a longer description of this module, containing some +commentary with @some markup@. +-} +module W where ... + + The Module field should be clear. It + currently doesn't affect the output of any of the backends but + you might want to include it for human information or for any + other tools that might be parsing these comments without the + help of GHC. + + The Description field accepts some short text + which outlines the general purpose of the module. If you're + generating HTML, it will show up next to the module link in + the module index. + + The Copyright, License, + Maintainer and Stability fields + should be obvious. An alternative spelling for the + License field is accepted as + Licence but the output will always prefer + License. + + The Portability field has seen varied use + by different library authors. Some people put down things like + operating system constraints there while others put down which + GHC extensions used. Note that you might want to consider using + the show-extensions module flag for the + latter. + + Finally, a module may contain a documentation comment + before the module header, in which case this comment is + interpreted by Haddock as an overall description of the module + itself, and placed in a section entitled + Description in the documentation for the module. + All usual Haddock markup is valid in this comment. + + All fields are optional but they must be in order if they + do appear. Multi-line fields are accepted but the consecutive + lines have to start indented more than their label. If your + label is indented one space as is often the case with + -- syntax, the consecutive lines have to start at + two spaces at the very least. Please note that we do not enforce + the format for any of the fields and the established formats are + just a convention. +
-- cgit v1.2.3