[[haddock @ 2002-04-26 16:01:44 by simonmar] simonmar**20020426160144 Yet more keyboard bashing - this is pretty much complete now. ] { hunk ./doc/haddock.sgml 162 + +
+ Acknowledgements + + Several documentation systems provided the inspiration for + Haddock, most notably: + + + + + IDoc + + + HDoc + + + + Doxygen + + + + and probably several others I've forgotten. + + Thanks to the following people for useful feedback, + discussion, patches, and moral support: Simon Peyton Jones, Mark + Shields, Manuel Chakravarty, Ross Patterson, Brett Letner, the + members of haskelldoc@haskell.org, and everyone + who contributed to the many libraries that Haddock makes use + of. +
+ hunk ./doc/haddock.sgml 379 + hunk ./doc/haddock.sgml 424 + +
+ Documenting parts of a declaration + + In addition to documenting the whole declaration, in some + cases we can also document individual parts of the + declaration. + +
+ Class methods + + Class methods are documented in the same way as top + level type signatures, by using either the + -- | or + -- ^ + annotations: + + +class C a where + -- | This is the documentation for the 'f' method + f :: a -> Int + -- | This is the documentation for the 'g' method + g :: Int -> a + + + Note that in Haddock documentation annotations are + first-class syntactic objects that are subject to the same + layout rules as other syntactic objects; thus in the example + class declaration above the documentation annotations must + begin in the same column as the method signatures. If you use + explicit layout, then don't forget the semi-colon after each + documentation comment (but don't put the semi-colon on the + same line as the documentation comment, because it will be + interpreted as part of the documentation!). +
+ +
+ Constructors and record fields + + Constructors are documented like so: + + +data T a b + = -- | This is the documentation for the 'C1' constructor + C1 a b + | -- | This is the documentation for the 'C2' constructor + C2 a b + + + or like this: + + +data T a b + = C1 a b -- ^ This is the documentation for the 'C1' constructor + | C2 a b -- ^ This is the documentation for the 'C2' constructor + + + Record fields are documented using one of these + styles: + + +data R a b = + C { -- | This is the documentation for the 'a' field + a :: a, + -- | This is the documentation for the 'b' field + b :: b + } + +data R a b = + C { a :: a, -- ^ This is the documentation for the 'a' field + b :: b -- ^ This is the documentation for the 'b' field + } + +
+ hunk ./doc/haddock.sgml 500 - Controlling the documentation structure + Function arguments + + Individual arguments to a function may be documented + like this: + + +f :: Int -- | The 'Int' argument + -> Float -- | The 'Float' argument + -> IO () -- | The return value + + + NOTE: this feature isn't implemented in Haddock + 1.0. +
+ + +
+ 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: + + +-- | This is the description for module "Foo" +module Foo where +... + +
+ +
+ Controlling the documentation structure hunk ./doc/haddock.sgml 535 - Haddock produces interface documentation that lists only - the entities actually exported by the module. The - documentation for a module will include - all entities exported by that module, - even if they were re-exported by another module. The only - exception is when Haddock can't see the declaration for the - re-exported entity, perhaps because it isn't part of the batch - of modules currently being processed. + Haddock produces interface documentation that lists only + the entities actually exported by the module. The documentation + for a module will include all entities + exported by that module, even if they were re-exported by + another module. The only exception is when Haddock can't see + the declaration for the re-exported entity, perhaps because it + isn't part of the batch of modules currently being + processed. hunk ./doc/haddock.sgml 544 - However, to Haddock the export list has even more - significance than just specifying the entities to be included - in the documentation. It also specifies the - order that entities will be listed in the - generated documentation. This leaves the programmer free to - implement functions in any order he/she pleases, and indeed in - any module he/she pleases, but still - specify the order that the functions should be documented in - the export list. Indeed, many programmers already do this: - the export list is often used as a kind of ad-hoc interface - documentation, with headings, groups of functions, type - signatures and declarations in comments. + However, to Haddock the export list has even more + significance than just specifying the entities to be included in + the documentation. It also specifies the + order that entities will be listed in the + generated documentation. This leaves the programmer free to + implement functions in any order he/she pleases, and indeed in + any module he/she pleases, but still + specify the order that the functions should be documented in the + export list. Indeed, many programmers already do this: the + export list is often used as a kind of ad-hoc interface + documentation, with headings, groups of functions, type + signatures and declarations in comments. hunk ./doc/haddock.sgml 557 - You can insert headings and sub-headings in the - documentation by including annotations at the appropriate - point in the export list. For example: + You can insert headings and sub-headings in the + documentation by including annotations at the appropriate point + in the export list. For example: hunk ./doc/haddock.sgml 574 - - Headings are introduced with the syntax - - -- *, - -- ** - - and so on, where the number of *s indicates - the level of the heading (section, sub-section, - sub-sub-section, etc.). hunk ./doc/haddock.sgml 575 - If you use section headings, then Haddock will generate - a table of contents at the top of the module documentation for - you. + Headings are introduced with the syntax + -- *, + -- ** and so on, where + the number of *s indicates the level of the + heading (section, sub-section, sub-sub-section, etc.). hunk ./doc/haddock.sgml 581 -
- Re-exporting an entire module + If you use section headings, then Haddock will generate a + table of contents at the top of the module documentation for + you. hunk ./doc/haddock.sgml 585 - Haskell allows you to re-export the entire contents of - a module (or at least, everything currently in scope that - was imported from a given module) by listing it in the - export list: +
+ Re-exporting an entire module + + Haskell allows you to re-export the entire contents of a + module (or at least, everything currently in scope that was + imported from a given module) by listing it in the export + list: hunk ./doc/haddock.sgml 600 - What will the Haddock-generated documentation for this - module look like? Well, Haddock simply behaves as if the - export list for modules Bar and - Baz had been expanded in-place in the - export list for Foo, including all of - their structure (section headings etc.). -
+ What will the Haddock-generated documentation for this + module look like? Well, Haddock simply behaves as if the + export list for modules Bar and + Baz had been expanded in-place in the + export list for Foo, including all of their + structure (section headings etc.). +
+ +
+ Omitting the export list + + If there is no export list in the module, how does + Haddock generate documentation? Well, when the export list is + omitted, e.g.: hunk ./doc/haddock.sgml 615 -
- More about re-exported entities - - How hyperlinks are re-targetted when an entity is - re-exported. +module Foo where hunk ./doc/haddock.sgml 617 -
+ this is equivalent to an export list which mentions + every entity defined at the top level in this module, and + Haddock treats it in the same way. Furthermore, the generated + documentation will retain the order in which entities are + defined in the module. In this special case the module body + may also include section headings (normally they would be + ignored by Haddock). hunk ./doc/haddock.sgml 625 - hunk ./doc/haddock.sgml 628 - The module description - + Named chunks of documentation + + Occasionally it is desirable to include a chunk of + documentation which is not attached to any particular Haskell + declaration. There are two ways to do this: + + + + The documentation can be included in the export list + directly, e.g.: + + +module Foo ( + -- * A section heading + -- | Some documentation not attached to a particular Haskell entity + ... + ) where + + + + + If the documentation is large and placing it inline in + the export list might bloat the export list and obscure the + structure, then it can be given a name and placed out of + line in the body of the module. This is achieved with a + special form of documentation annotation + -- $: + + +module Foo ( + -- * A section heading + -- $doc + ... + ) where + +-- $doc +-- Here is a large chunk of documentation which may be referred to by +-- the name $doc. + + + The documentation chunk is given a name, which is the + sequence of alphanumeric characters directly after the + -- $, and it may be + referred to by the same name in the export list. + + hunk ./doc/haddock.sgml 675 - + hunk ./doc/haddock.sgml 677 - Named chunks of documentation - + Hyperlinking and re-exported entities + + When Haddock renders a type in the generated + documentation, it hyperlinks all the type constructors and class + names in that type to their respective definitions. But for a + given type constructor or class there may be several modules + re-exporting it, and therefore several modules whose + documentation contains the definition of that type or class + (possibly including the current module!) so which one do we link + to? + + Let's look at an example. Suppose we have three modules + A, B and + C defined as follows: + + +module A (T) where +data T a = C a + +module B (f) where +import A +f :: T Int -> Int +f (C i) = i + +module C (T, f) where +import A +import B + + + Module A exports a datatype + T. Module B imports + A and exports a function f + whose type refers to T: the hyperlink in + f's signature will point to the definition of + T in the documentation for module + A. + + Now, module C exports both + T and f. We have a choice + about where to point the hyperlink to T in + f's type: either the definition exported by + module C or the definition exported by module + A. Haddock takes the view that in this case + pointing to the definition in C is better, + because the programmer might not wish to expose + A to the programmer at all: + A might be a module internal to the + implementation of the library in which C is + the external interface, so linking to definitions in the current + module is preferrable over an imported module. + + The general rule is this: when attempting to link an + instance of a type constructor or class to its definition, the + link is made to + + + the current module, if the current module exports the + relevant definition, or + + + the module that the entity was imported from, + otherwise. If the entity was imported via multiple routes, + then Haddock picks the module listed earliest in the imports + of the current module. + + hunk ./doc/haddock.sgml 744 - + hunk ./doc/haddock.sgml 747 - - links to identifiers - links to modules - itemized lists - enumerated lists - emphasis - code blocks - URLs + + Haddock understands certain textual queues inside + documentation annotations that tell it how to render the + documentation. The queues (or markup) have been + designed to be simple and mnemonic in ASCII so that the + programmer doesn't have to deal with heavyweight annotations + when editing documentation comments. + +
+ Paragraphs + + One or more blank lines separates two paragraphs in a + documentation comment. +
+ +
+ Special characters + + The following characters have special meanings in + documentation comments: /, + ', [, + ], <. To insert a + literal occurrence of one of these special characters, precede + it with a backslash (\). + + Additionally, the following characters have special + meanings at the beginning of a paragraph: + *, -. These characters + can also be escaped using \. + +
+ +
+ Emphasis and Monospaced text + + Emphasis may be added by surrounding text with + /.../. + + Monospaced (or typewriter) text is indicated by + surrounding it with [...]. +
+ +
+ Code Blocks + + Displayed blocks of code are indicated by surrounding a + paragraph with [...] or by preceding each + line of a paragraph with >. For + example: + + +-- | This documentation includes two blocks of code: +-- +-- [ +-- f x = x + x +-- ] +-- +-- > g x = x * 42 + +
+ +
+ Hyperlinked Identifiers + + Referring to a Haskell identifier, whether it be a type, + class, constructor, or function, is done by surrounding it + with single quotes: + + +-- | This module defines the type 'T'. + + + If there is an entity T in scope in + the current module, then the documentation will hyperlink the + reference in the text to the definition of + T (if the output format supports + hyperlinking, of course; in a printed format it might instead + insert a page reference to the definition). +
+ +
+ Linking to modules + + Linking to a module is done by surrounding the module + name with double quotes: + + +-- | This is a reference to the "Foo" module. + + +
+ +
+ Itemized and Enumerated lists + + A bulleted item is represented by preceding a paragraph + with either * or + -. A sequence of bulleted + paragraphs is rendered as an itemized list in the generated + documentation, eg.: + + +-- | This is a bulleted list: +-- +-- * first item +-- +-- * second item + + + An enumerated list is similar, except each paragraph + must be preceded by either + (n) + or + n. + where n is any integer. e.g. + + +-- | This is an enumerated list: +-- +-- (1) first item +-- +-- 2. second item + +
+ +
+ URLs + + A URL can be included in a documentation comment by + surrounding it in angle brackets: + <...>. If the output format supports + it, the URL will be turned into a hyperlink when + rendered. +
}