Haddock User Guide

[[haddock @ 2004-08-16 19:59:36 by panne] panne**20040816195938 XMLification ] { addfile ./doc/haddock.xml hunk ./doc/Makefile 4 -SGML_DOC = haddock -INSTALL_SGML_DOC = haddock +XML_DOC = haddock +INSTALL_XML_DOC = haddock hunk ./doc/haddock.sgml 1 - - - - - 2004-08-02 - Haddock User Guide - - Simon - Marlow - -

simonmar@microsoft.com

- - 2004 - Simon Marlow - - - This document describes Haddock version 0.6, a Haskell - documentation tool. - - - - - - - - Introduction - - This is Haddock, a tool for automatically generating - documentation from annotated Haskell source code. Haddock was - designed with several goals in mind: - - - - When documenting APIs, it is desirable to keep the - documentation close to the actual interface or implementation - of the API, preferably in the same file, to reduce the risk - that the two become out of sync. Haddock therefore lets you - write the documentation for an entity (function, type, or - class) next to the definition of the entity in the source - code. - - - There is s tremendous amount of useful API documentation - that can be extracted from just the bare source code, - including types of exported functions, definitions of data - types and classes, and so on. Haddock can therefore generate - documentation from a set of straight Haskell 98 modules, and - the documentation will contain precisely the interface that is - available to a programmer using those modules. - - - Documentation annotations in the source code should be - easy on the eye when editing the source code itself, so as not - to obsure the code and to make reading and writing - documentation annotations easy. The easier it is to write - documentation, the more likely the programmer is to do it. - Haddock therefore uses lightweight markup in its annotations, - taking several ideas from IDoc. - In fact, Haddock can understand IDoc-annotated source - code. - - - The documentation should not expose any of the structure - of the implementation, or to put it another way, the - implementer of the API should be free to structure the - implementation however he or she wishes, without exposing any - of that structure to the consumer. In practical terms, this - means that while an API may internally consist of several - Haskell modules, we often only want to expose a single module - to the user of the interface, where this single module just - re-exports the relevant parts of the implementation - modules. - - Haddock therefore understands the Haskell module system - and can generate documentation which hides not only - non-exported entities from the interface, but also the - internal module structure of the interface. A documentation - annotation can still be placed next to the implementation, and - it will be propagated to the external module in the generated - documentation. - - - Being able to move around the documentation by following - hyperlinks is essential. Documentation generated by Haddock - is therefore littered with hyperlinks: every type and class - name is a link to the corresponding definition, and - user-written documentation annotations can contain identifiers - which are linked automatically when the documentation is - generated. - - - We might want documentation in multiple formats - online - and printed, for example. Haddock comes with HTML and DocBook - backends, and it is structured in such a way that adding new - back-ends is straightforward. - - - -

- Obtaining Haddock - - Distributions (source & binary) of Haddock can be obtained - from its web - site. - - Up-to-date sources can also be obtained from CVS. The - Haddock sources are under fptools/haddock in - the fptools CVS repository, which also - contains GHC, Happy, and several other projects. See Using - The CVS Repository for information on how to access the - CVS repository. Note that you need to check out the - fpconfig module first to get the generic - build system (the fptools directory), and - then check out fptools/haddock to get the - Haddock sources. -

- -

- License - - The following license covers this documentation, and the - Haddock source code, except where otherwise indicated. - -

- Copyright 2002, Simon Marlow. All rights reserved. - - Redistribution and use in source and binary forms, with - or without modification, are permitted provided that the - following conditions are met: - - - - Redistributions of source code must retain the above - copyright notice, this list of conditions and the - following disclaimer. - - - Redistributions in binary form must reproduce the - above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other - materials provided with the distribution. - - - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS - IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND - FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT - SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; - OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF - THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY - OF SUCH DAMAGE. -

- -

- 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, packaging, and moral support: Simon Peyton - Jones, Mark Shields, Manuel Chakravarty, Ross Patterson, Brett - Letner, Sven Panne, Hal Daume, George Russell, Oliver Braun, - Ashley Yakeley, Malcolm Wallace, Krasimir Angelov, the members - of haskelldoc@haskell.org, and everyone who - contributed to the many libraries that Haddock makes use - of. -

- - - - - Invoking Haddock - Haddock is invoked from the command line, like so: - - - haddock - option - file - - - Where each file is a filename - containing a Haskell source module. Only plain Haskell source - files are accepted (but see for instructions - on how to pre-process source files for feeding to Haddock). - - All the modules specified on the command line will be - processed together. When one module refers to an entity in - another module being processed, the documentation will link - directly to that entity. - - Entities that cannot be found, for example because they are - in a module that isn't being processed as part of the current - batch, simply won't be hyperlinked in the generated - documentation. Haddock will emit warnings listing all the - indentifiers it couldn't resolve. - - The modules should not be mutually - recursive, as Haddock don't like swimming in circles. - - The following options are available: - - - - - - dir - - - - =dir - - - Generate files into dir - instead of the current directory. - - - - - - - path,file - - - - =path,file - - - Read the interface file in - file, which must have been - produced by running Haddock with the - option. The interface - describes a set of modules whose HTML documentation is - located in path (which may be a - relative pathname). The path is - optional, and defaults to .. - - This option allows Haddock to produce separate sets of - documentation with hyperlinks between them. The - path is used to direct hyperlinks - to point to the right files; so make sure you don't move the - HTML files later or these links will break. Using a - relative path means that a - documentation subtree can still be moved around without - breaking links. - - Multiple options may - be given. - - - - - - - file - - - - =file - - - Produce an interface - fileHaddock interface files are - not the same as Haskell interface files, I just couldn't - think of a better name. - in the file file. An interface - file contains information Haddock needs to produce more - documentation that refers to the modules currently being - processed - see the option - for more details. The interface file is in a binary format; - don't try to read it. - - - - - - - dir - - - - =dir - - - Use auxiliary files in dir. - - - - - - - - - - - - - - Reserved for future use (output documentation in SGML DocBook - format). - - - - - - - - - - - - - - Generate documentation in HTML format. Several files - will be generated into the current directory (or the - specified directory if the option is - given), including the following: - - - index.html - - The top level page of the documentation: lists - the modules available, using indentation to represent - the hierarchy if the modules are hierarchical. - - - - haddock.css - - The stylesheet used by the generated HTML. Feel - free to modify this to change the colors or - layout, or even specify your own stylesheet using the - option. - - - - haddock.js - - A small piece of JavaScript for collapsing sections - of the generated HTML. - - - - module.html - - An HTML page for each - module. - - - - doc-index.html - doc-index-XX.html - - The index, split into two - (functions/constructors and types/classes, as per - Haskell namespaces) and further split - alphabetically. - - - - - - - - - - - - - - - - - (In HTML mode only) Produce extra contents and index - files for given HTML Help system. Currently supported Help - systems are Microsoft HTML Help 1.3 and 2.0 and GNOME DevHelp. - - Using the Microsoft HTML Help system provides two - advantages over plain HTML: the help viewer gives you a nice - hierarchical folding contents pane on the left, and the - documentation files are compressed and therefore much - smaller (roughly a factor of 10). The disadvantage is that - the help can't be viewed over the web. - - In order to create a compiled Microsoft help file, you - also need the Microsoft HTML Help compiler, which is - available free from - http://www.microsoft.com/ - (search for HTML Help compiler). - - Viewers - - - Microsoft HTML Help Viewer - Distributed with Microsoft Windows - - - xCHM - a CHM viewer for UNIX (Linux, *BSD, Solaris), written by Razvan Cojocaru - - - JouleData Solutions' CHM Viewer - a comercial 100% native Cocoa .chm file viewer for the Mac OS X platform - - - GnoCHM - a CHM file viewer. It is designed to integrate nicely with Gnome. - - - - The GNOME DevHelp also provides help viewer which looks like - MSHelp viewer but the documentation files aren't compressed. - The documentation can be viewed with any HTML browser but - DevHelp gives you a nice hierarchical folding contents and - keyword index panes on the left. The DevHelp expects to see - *.devhelp file in the folder where the documentation is placed. - The file contains all required information - to build the contents and index panes. - - - - - - - - URL - - - - =URL - - - Include links to the source files in the generated - documentation, where URL is the - base URL where the source files can be found. - - - - - - - file - - - - =file - - - Specify a stylesheet to use instead of the default one - that comes with Haddock. It should specify certain classes: - see the default stylesheet for details. - - - - - - - file - - - - =file - - - Specify a file containing documentation which is - placed on the main contents page under the heading - “Description”. The file is parsed as a normal - Haddock doc comment (but the comment markers are not - required). - - - - - - - title - - - - =title - - - Use title as the page - heading for each page in the documentation.This will - normally be the name of the library being documented. - - The title should be a plain string (no markup - please!). - - - - - - - - - - - - - - Don't automatically import Prelude - in every module. Used when producing documentation for the - Prelude itself. - - - - - - - - - - - - - - Produce extra debugging output. - - - - - - - - - - - - - - Display help and exit. - - - - - - - - - - - - - - Increase verbosity. Currently this will cause Haddock - to emit some extra warnings, in particular about modules - which were imported but it had no information about (this is - often quite normal; for example when there is no information - about the Prelude). - - - - - - - - - - - - - - Output version information and exit. - - - - - - - - - - When generating HTML, do not generate an index. - Instead, redirect the Index link on each page to - URL. This option is intended for - use in conjuction with for - generating a separate index covering multiple - libraries. - - - - - - - - - - Generate an HTML index containing entries pulled from - all the specified interfaces (interfaces are specified using - or ). - This is used to generate a single index for multiple sets of - Haddock documentstation. - - - - - - - P - - - - P - - - Set the package name for these modules to - P. In a combined index generated - with , the package name for each - module is shown in the right-hand column. - - - - -

- Using literate or pre-processed source - - Haddock only accepts plain, non-literate, Haskell source. - This means that if you program in Literate Haskell, or you need - to use the C pre-processor in your Haskell source, then you need - to pre-process the files before feeding them to Haddock. This - is easily accomplished using GHC; for example, suppose we have a - Literate Haskell source file Foo.lhs, on - which we also need to run the C pre-processor: - - -$ ghc -cpp -E -optP-P -D__HADDOCK__ Foo.lhs -o Foo.hs -$ haddock -h Foo.hs ... - - - The option to GHC says "stop after - pre-processing", the option turns on the C - pre-processor, the option tells the C - pre-processor not to leave any extra dropping behind (see the - description of the option in the gcc manual - for details), and the option - defines the symbol __HADDOCK__ when - pre-processing (this is sometimes handy if you need to any - pre-processing conditionals in your source which depend on - whether the source is going to be fed to Haddock). -

- - - - - Documentation and Markup - - Haddock understands special documentation annotations in the - Haskell source file and propagates these into the generated - documentation. The annotations are purely optional: if there are - no annotations, Haddock will just generate documentation that - contains the type signatures, data type declarations, and class - declarations exported by each of the modules being - processed. - -

- Documenting a top-level declaration - - The simplest example of a documentation annotation is for - documenting any top-level declaration (function type signature, - type declaration, or class declaration). For example, if the - source file contains the following type signature: - - -square :: Int -> Int -square x = x * x - - - Then we can document it like this: - - --- |The 'square' function squares an integer. -square :: Int -> Int -square x = x * x - - - - The -- | syntax begins a - documentation annotation, which applies to the - following declaration in the source file. - Note that the annotation is just a comment in Haskell — it - will be ignored by the Haskell compiler. - - The declaration following a documentation annotation - should be one of the following: - - - A type signature for a top-level function, - - - A data declaration, - - - A newtype declaration, - - - A type declaration, or - - - A class declaration. - - - - If the annotation is followed by a different kind of - declaration, it will probably be ignored by Haddock. - - Some people like to write their documentation - after the declaration; this is possible in - Haddock too: - - -square :: Int -> Int --- ^The 'square' function squares an integer. -square x = x * x - - - Note that Haddock doesn't contain a Haskell type system - — if you don't write the type signature for a function, - then Haddock can't tell what its type is and it won't be - included in the documentation. - - Documentation annotations may span several lines; the - annotation continues until the first non-comment line in the - source file. For example: - - --- |The 'square' function squares an integer. --- It takes one argument, of type 'Int'. -square :: Int -> Int -square x = x * x - - - You can also use Haskell's nested-comment style for - documentation annotations, which is sometimes more convenient - when using multi-line comments: - - -{-| - The 'square' function squares an integer. - It takes one argument, of type 'Int'. --} -square :: Int -> Int -square x = x * x - - -

- 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 - -

- -

- 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 - } - - - Alternative layout styles are generally accepted by - Haddock - for example doc comments can appear before or after - the comma in separated lists such as the list of record fields - above. -

- -

- 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 - -

- -

- 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 - - 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. - - 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. - - You can insert headings and sub-headings in the - documentation by including annotations at the appropriate point - in the export list. For example: - - -module Foo ( - -- * Classes - C(..), - -- * Types - -- ** A data type - T, - -- ** A record - R, - -- * Some functions - f, g - ) where - - - 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.). - - If you use section headings, then Haddock will generate a - table of contents at the top of the module documentation for - you. - - The alternative style of placing the commas at the - beginning of each line is also supported. eg.: - - -module Foo ( - -- * Classes - , C(..) - -- * Types - -- ** A data type - , T - -- ** A record - , R - -- * Some functions - , f - , g - ) where - - -

- 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: - - -module A ( - module B, - module C - ) where - - - What will the Haddock-generated documentation for this - module look like? Well, it depends on how the modules - B and C are imported. - If they are imported wholly and without any - hiding qualifiers, then the documentation - will just contain a cross-reference to the documentation for - B and C. However, if - the modules are not completely - re-exported, for example: - - -module A ( - module B, - module C - ) where - -import B hiding (f) -import C (a, b) - - - then Haddock behaves as if the set of entities - re-exported from B and C - had been listed explicitly in the export - listNOTE: this is not fully implemented at the - time of writing (version 0.2). At the moment, Haddock always - inserts a cross-reference. - . - - The exception to this rule is when the re-exported - module is declared with the hide attribute - (), in which case the module - is never cross-referenced; the contents are always expanded in - place in the re-exporting module. -

- -

- 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.: - -module Foo where - - 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). -

- -

- 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. - - -

- -

- 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. - - -

- -

- Module Attributes - - Certain attributes may be specified for each module which - affects the way that Haddock generates documentation for that - module. Attributes are specified in a comma-separated list in a - -- # (or - {- # ... -}) comment at the - top of the module, either before or after the module - description. For example: - - --- #hide, prune, ignore-exports --- |Module description -module A where -... - - - The following attributes are currently understood by - Haddock: - - - - - hide - hide - - - Omit this module from the generated documentation, - but nevertheless propagate definitions and documentation - from within this module to modules that re-export those - definitions. - - - - - - hide - prune - - - Omit definitions that have no documentation - annotations from the generated documentation. - - - - - - hide - ignore-exports - - - Ignore the export list. Generate documentation as - if the module had no export list - i.e. all the top-level - declarations are exported, and section headings may be - given in the body of the module. - - - -

- -

- Markup - - Haddock understands certain textual cues inside - documentation annotations that tell it how to render the - documentation. The cues (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 character > has - a special meaning at the beginning of a line, and the - following characters have special meanings at the beginning of - a paragraph: - *, -. These characters - can also be escaped using \. -

- -

- Code Blocks - - Displayed blocks of code are indicated by surrounding a - paragraph with @...@ or by preceding each - line of a paragraph with > (we often - call these “bird tracks”). For - example: - - --- | This documentation includes two blocks of code: --- --- @ --- f x = x + x --- @ --- --- > g x = x * 42 - - - There is an important difference between the two forms - of code block: in the bird-track form, the text to the right - of the ‘>’ is interpreted - literally, whereas the @...@ form - interprets markup as normal inside the code block. -

- -

- 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). - - It is also possible to refer to entities that are not in - scope in the current module, by giving the full qualified name - of the entity: - - --- | The identifier 'M.T' is not in scope - - - If M.T is not otherwise in scope, - then Haddock will simply emit a link pointing to the entity - T exported from module M - (without checking to see whether either M - or M.T exist). - - To make life easier for documentation writers, a quoted - identifier is only interpreted as such if the quotes surround - a lexically valid Haskell identifier. This means, for - example, that it normally isn't necessary to escape the single - quote when used as an apostrophe: - - --- | I don't have to escape my apostrophes; great, isn't it? - - - For compatibility with other systems, the following - alternative form of markup is accepted - We chose not to use this as the primary markup for - identifiers because strictly speaking the ` - character should not be used as a left quote, it is a grave accent. - : `T'. -

- -

- Emphasis and Monospaced text - - Emphasis may be added by surrounding text with - /.../. - - Monospaced (or typewriter) text is indicated by - surrounding it with @...@. Other markup is - valid inside a monospaced span: for example - @'f' a b@ will hyperlink the - identifier f inside the code fragment. -

- -

- 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 - -

- -

- Definition lists - - Definition lists are written as follows: - - --- | This is a definition list: --- --- [@foo@] The description of @foo@. --- --- [@bar@] The description of @bar@. - - - To produce output something like this: - - - - foo - - The description of foo. - - - - bar - - The description of bar. - - - - - Each paragraph should be preceded by the - “definition term” enclosed in square brackets. - The square bracket characters have no special meaning outside - the beginning of a definition paragraph. That is, if a - paragraph begins with a [ character, then - it is assumed to be a definition paragraph, and the next - ] character found will close the definition - term. Other markup operators may be used freely within the - definition term. -

- -

- 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. -

- -

- Anchors - - Sometimes it is useful to be able to link to a point in - the documentation which doesn't correspond to a particular - entity. For that purpose, we allow anchors to be - included in a documentation comment. The syntax is - #label#, where - label is the name of the anchor. - An anchor is invisible in the generated documentation. - - To link to an anchor from elsewhere, use the syntax - "module#label" - where module is the module name - containing the anchor, and label is - the anchor label. The module does not have to be local, it - can be imported via an interface. -

- - rmfile ./doc/haddock.sgml hunk ./doc/haddock.xml 1 + + + + + + 2004-08-02 + Haddock User Guide + + Simon + Marlow + +

simonmar@microsoft.com

+ + 2004 + Simon Marlow + + + This document describes Haddock version 0.6, a Haskell + documentation tool. + + + + + + + + Introduction + + This is Haddock, a tool for automatically generating + documentation from annotated Haskell source code. Haddock was + designed with several goals in mind: + + + + When documenting APIs, it is desirable to keep the + documentation close to the actual interface or implementation + of the API, preferably in the same file, to reduce the risk + that the two become out of sync. Haddock therefore lets you + write the documentation for an entity (function, type, or + class) next to the definition of the entity in the source + code. + + + There is s tremendous amount of useful API documentation + that can be extracted from just the bare source code, + including types of exported functions, definitions of data + types and classes, and so on. Haddock can therefore generate + documentation from a set of straight Haskell 98 modules, and + the documentation will contain precisely the interface that is + available to a programmer using those modules. + + + Documentation annotations in the source code should be + easy on the eye when editing the source code itself, so as not + to obsure the code and to make reading and writing + documentation annotations easy. The easier it is to write + documentation, the more likely the programmer is to do it. + Haddock therefore uses lightweight markup in its annotations, + taking several ideas from IDoc. + In fact, Haddock can understand IDoc-annotated source + code. + + + The documentation should not expose any of the structure + of the implementation, or to put it another way, the + implementer of the API should be free to structure the + implementation however he or she wishes, without exposing any + of that structure to the consumer. In practical terms, this + means that while an API may internally consist of several + Haskell modules, we often only want to expose a single module + to the user of the interface, where this single module just + re-exports the relevant parts of the implementation + modules. + + Haddock therefore understands the Haskell module system + and can generate documentation which hides not only + non-exported entities from the interface, but also the + internal module structure of the interface. A documentation + annotation can still be placed next to the implementation, and + it will be propagated to the external module in the generated + documentation. + + + Being able to move around the documentation by following + hyperlinks is essential. Documentation generated by Haddock + is therefore littered with hyperlinks: every type and class + name is a link to the corresponding definition, and + user-written documentation annotations can contain identifiers + which are linked automatically when the documentation is + generated. + + + We might want documentation in multiple formats - online + and printed, for example. Haddock comes with HTML and DocBook + backends, and it is structured in such a way that adding new + back-ends is straightforward. + + + +

+ Obtaining Haddock + + Distributions (source & binary) of Haddock can be obtained + from its web + site. + + Up-to-date sources can also be obtained from CVS. The + Haddock sources are under fptools/haddock in + the fptools CVS repository, which also + contains GHC, Happy, and several other projects. See Using + The CVS Repository for information on how to access the + CVS repository. Note that you need to check out the + fpconfig module first to get the generic + build system (the fptools directory), and + then check out fptools/haddock to get the + Haddock sources. +

+ +

+ License + + The following license covers this documentation, and the + Haddock source code, except where otherwise indicated. + +

+ Copyright 2002, Simon Marlow. All rights reserved. + + Redistribution and use in source and binary forms, with + or without modification, are permitted provided that the + following conditions are met: + + + + Redistributions of source code must retain the above + copyright notice, this list of conditions and the + following disclaimer. + + + Redistributions in binary form must reproduce the + above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other + materials provided with the distribution. + + + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS + IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT + SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; + OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF + THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY + OF SUCH DAMAGE. +

+ +

+ 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, packaging, and moral support: Simon Peyton + Jones, Mark Shields, Manuel Chakravarty, Ross Patterson, Brett + Letner, Sven Panne, Hal Daume, George Russell, Oliver Braun, + Ashley Yakeley, Malcolm Wallace, Krasimir Angelov, the members + of haskelldoc@haskell.org, and everyone who + contributed to the many libraries that Haddock makes use + of. +

+ + + + + Invoking Haddock + Haddock is invoked from the command line, like so: + + + haddock + option + file + + + Where each file is a filename + containing a Haskell source module. Only plain Haskell source + files are accepted (but see for instructions + on how to pre-process source files for feeding to Haddock). + + All the modules specified on the command line will be + processed together. When one module refers to an entity in + another module being processed, the documentation will link + directly to that entity. + + Entities that cannot be found, for example because they are + in a module that isn't being processed as part of the current + batch, simply won't be hyperlinked in the generated + documentation. Haddock will emit warnings listing all the + indentifiers it couldn't resolve. + + The modules should not be mutually + recursive, as Haddock don't like swimming in circles. + + The following options are available: + + + + + + dir + + + + =dir + + + Generate files into dir + instead of the current directory. + + + + + + + path,file + + + + =path,file + + + Read the interface file in + file, which must have been + produced by running Haddock with the + option. The interface + describes a set of modules whose HTML documentation is + located in path (which may be a + relative pathname). The path is + optional, and defaults to .. + + This option allows Haddock to produce separate sets of + documentation with hyperlinks between them. The + path is used to direct hyperlinks + to point to the right files; so make sure you don't move the + HTML files later or these links will break. Using a + relative path means that a + documentation subtree can still be moved around without + breaking links. + + Multiple options may + be given. + + + + + + + file + + + + =file + + + Produce an interface + fileHaddock interface files are + not the same as Haskell interface files, I just couldn't + think of a better name. + in the file file. An interface + file contains information Haddock needs to produce more + documentation that refers to the modules currently being + processed - see the option + for more details. The interface file is in a binary format; + don't try to read it. + + + + + + + dir + + + + =dir + + + Use auxiliary files in dir. + + + + + + + + + + + + + + Reserved for future use (output documentation in SGML DocBook + format). + + + + + + + + + + + + + + Generate documentation in HTML format. Several files + will be generated into the current directory (or the + specified directory if the option is + given), including the following: + + + index.html + + The top level page of the documentation: lists + the modules available, using indentation to represent + the hierarchy if the modules are hierarchical. + + + + haddock.css + + The stylesheet used by the generated HTML. Feel + free to modify this to change the colors or + layout, or even specify your own stylesheet using the + option. + + + + haddock.js + + A small piece of JavaScript for collapsing sections + of the generated HTML. + + + + module.html + + An HTML page for each + module. + + + + doc-index.html + doc-index-XX.html + + The index, split into two + (functions/constructors and types/classes, as per + Haskell namespaces) and further split + alphabetically. + + + + + + + + + + + + + + + + + (In HTML mode only) Produce extra contents and index + files for given HTML Help system. Currently supported Help + systems are Microsoft HTML Help 1.3 and 2.0 and GNOME DevHelp. + + Using the Microsoft HTML Help system provides two + advantages over plain HTML: the help viewer gives you a nice + hierarchical folding contents pane on the left, and the + documentation files are compressed and therefore much + smaller (roughly a factor of 10). The disadvantage is that + the help can't be viewed over the web. + + In order to create a compiled Microsoft help file, you + also need the Microsoft HTML Help compiler, which is + available free from + http://www.microsoft.com/ + (search for HTML Help compiler). + + Viewers + + + Microsoft HTML Help Viewer + Distributed with Microsoft Windows + + + xCHM + a CHM viewer for UNIX (Linux, *BSD, Solaris), written by Razvan Cojocaru + + + JouleData Solutions' CHM Viewer + a comercial 100% native Cocoa .chm file viewer for the Mac OS X platform + + + GnoCHM + a CHM file viewer. It is designed to integrate nicely with Gnome. + + + + The GNOME DevHelp also provides help viewer which looks like + MSHelp viewer but the documentation files aren't compressed. + The documentation can be viewed with any HTML browser but + DevHelp gives you a nice hierarchical folding contents and + keyword index panes on the left. The DevHelp expects to see + *.devhelp file in the folder where the documentation is placed. + The file contains all required information + to build the contents and index panes. + + + + + + + + URL + + + + =URL + + + Include links to the source files in the generated + documentation, where URL is the + base URL where the source files can be found. + + + + + + + file + + + + =file + + + Specify a stylesheet to use instead of the default one + that comes with Haddock. It should specify certain classes: + see the default stylesheet for details. + + + + + + + file + + + + =file + + + Specify a file containing documentation which is + placed on the main contents page under the heading + “Description”. The file is parsed as a normal + Haddock doc comment (but the comment markers are not + required). + + + + + + + title + + + + =title + + + Use title as the page + heading for each page in the documentation.This will + normally be the name of the library being documented. + + The title should be a plain string (no markup + please!). + + + + + + + + + + + + + + Don't automatically import Prelude + in every module. Used when producing documentation for the + Prelude itself. + + + + + + + + + + + + + + Produce extra debugging output. + + + + + + + + + + + + + + Display help and exit. + + + + + + + + + + + + + + Increase verbosity. Currently this will cause Haddock + to emit some extra warnings, in particular about modules + which were imported but it had no information about (this is + often quite normal; for example when there is no information + about the Prelude). + + + + + + + + + + + + + + Output version information and exit. + + + + + + + + + + When generating HTML, do not generate an index. + Instead, redirect the Index link on each page to + URL. This option is intended for + use in conjuction with for + generating a separate index covering multiple + libraries. + + + + + + + + + + Generate an HTML index containing entries pulled from + all the specified interfaces (interfaces are specified using + or ). + This is used to generate a single index for multiple sets of + Haddock documentstation. + + + + + + + P + + + + P + + + Set the package name for these modules to + P. In a combined index generated + with , the package name for each + module is shown in the right-hand column. + + + + +

+ Using literate or pre-processed source + + Haddock only accepts plain, non-literate, Haskell source. + This means that if you program in Literate Haskell, or you need + to use the C pre-processor in your Haskell source, then you need + to pre-process the files before feeding them to Haddock. This + is easily accomplished using GHC; for example, suppose we have a + Literate Haskell source file Foo.lhs, on + which we also need to run the C pre-processor: + + +$ ghc -cpp -E -optP-P -D__HADDOCK__ Foo.lhs -o Foo.hs +$ haddock -h Foo.hs ... + + + The option to GHC says "stop after + pre-processing", the option turns on the C + pre-processor, the option tells the C + pre-processor not to leave any extra dropping behind (see the + description of the option in the gcc manual + for details), and the option + defines the symbol __HADDOCK__ when + pre-processing (this is sometimes handy if you need to any + pre-processing conditionals in your source which depend on + whether the source is going to be fed to Haddock). +

+ + + + + Documentation and Markup + + Haddock understands special documentation annotations in the + Haskell source file and propagates these into the generated + documentation. The annotations are purely optional: if there are + no annotations, Haddock will just generate documentation that + contains the type signatures, data type declarations, and class + declarations exported by each of the modules being + processed. + +

+ Documenting a top-level declaration + + The simplest example of a documentation annotation is for + documenting any top-level declaration (function type signature, + type declaration, or class declaration). For example, if the + source file contains the following type signature: + + +square :: Int -> Int +square x = x * x + + + Then we can document it like this: + + +-- |The 'square' function squares an integer. +square :: Int -> Int +square x = x * x + + + + The -- | syntax begins a + documentation annotation, which applies to the + following declaration in the source file. + Note that the annotation is just a comment in Haskell — it + will be ignored by the Haskell compiler. + + The declaration following a documentation annotation + should be one of the following: + + + A type signature for a top-level function, + + + A data declaration, + + + A newtype declaration, + + + A type declaration, or + + + A class declaration. + + + + If the annotation is followed by a different kind of + declaration, it will probably be ignored by Haddock. + + Some people like to write their documentation + after the declaration; this is possible in + Haddock too: + + +square :: Int -> Int +-- ^The 'square' function squares an integer. +square x = x * x + + + Note that Haddock doesn't contain a Haskell type system + — if you don't write the type signature for a function, + then Haddock can't tell what its type is and it won't be + included in the documentation. + + Documentation annotations may span several lines; the + annotation continues until the first non-comment line in the + source file. For example: + + +-- |The 'square' function squares an integer. +-- It takes one argument, of type 'Int'. +square :: Int -> Int +square x = x * x + + + You can also use Haskell's nested-comment style for + documentation annotations, which is sometimes more convenient + when using multi-line comments: + + +{-| + The 'square' function squares an integer. + It takes one argument, of type 'Int'. +-} +square :: Int -> Int +square x = x * x + + +

+ 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 + +

+ +

+ 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 + } + + + Alternative layout styles are generally accepted by + Haddock - for example doc comments can appear before or after + the comma in separated lists such as the list of record fields + above. +

+ +

+ 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 + +

+ +

+ 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 + + 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. + + 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. + + You can insert headings and sub-headings in the + documentation by including annotations at the appropriate point + in the export list. For example: + + +module Foo ( + -- * Classes + C(..), + -- * Types + -- ** A data type + T, + -- ** A record + R, + -- * Some functions + f, g + ) where + + + 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.). + + If you use section headings, then Haddock will generate a + table of contents at the top of the module documentation for + you. + + The alternative style of placing the commas at the + beginning of each line is also supported. eg.: + + +module Foo ( + -- * Classes + , C(..) + -- * Types + -- ** A data type + , T + -- ** A record + , R + -- * Some functions + , f + , g + ) where + + +

+ 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: + + +module A ( + module B, + module C + ) where + + + What will the Haddock-generated documentation for this + module look like? Well, it depends on how the modules + B and C are imported. + If they are imported wholly and without any + hiding qualifiers, then the documentation + will just contain a cross-reference to the documentation for + B and C. However, if + the modules are not completely + re-exported, for example: + + +module A ( + module B, + module C + ) where + +import B hiding (f) +import C (a, b) + + + then Haddock behaves as if the set of entities + re-exported from B and C + had been listed explicitly in the export + listNOTE: this is not fully implemented at the + time of writing (version 0.2). At the moment, Haddock always + inserts a cross-reference. + . + + The exception to this rule is when the re-exported + module is declared with the hide attribute + (), in which case the module + is never cross-referenced; the contents are always expanded in + place in the re-exporting module. +

+ +

+ 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.: + +module Foo where + + 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). +

+ +

+ 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. + + +

+ +

+ 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. + + +

+ +

+ Module Attributes + + Certain attributes may be specified for each module which + affects the way that Haddock generates documentation for that + module. Attributes are specified in a comma-separated list in a + -- # (or + {- # ... -}) comment at the + top of the module, either before or after the module + description. For example: + + +-- #hide, prune, ignore-exports +-- |Module description +module A where +... + + + The following attributes are currently understood by + Haddock: + + + + + hide + hide + + + Omit this module from the generated documentation, + but nevertheless propagate definitions and documentation + from within this module to modules that re-export those + definitions. + + + + + + hide + prune + + + Omit definitions that have no documentation + annotations from the generated documentation. + + + + + + hide + ignore-exports + + + Ignore the export list. Generate documentation as + if the module had no export list - i.e. all the top-level + declarations are exported, and section headings may be + given in the body of the module. + + + +

+ +

+ Markup + + Haddock understands certain textual cues inside + documentation annotations that tell it how to render the + documentation. The cues (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 character > has + a special meaning at the beginning of a line, and the + following characters have special meanings at the beginning of + a paragraph: + *, -. These characters + can also be escaped using \. +

+ +

+ Code Blocks + + Displayed blocks of code are indicated by surrounding a + paragraph with @...@ or by preceding each + line of a paragraph with > (we often + call these “bird tracks”). For + example: + + +-- | This documentation includes two blocks of code: +-- +-- @ +-- f x = x + x +-- @ +-- +-- > g x = x * 42 + + + There is an important difference between the two forms + of code block: in the bird-track form, the text to the right + of the ‘>’ is interpreted + literally, whereas the @...@ form + interprets markup as normal inside the code block. +

+ +

+ 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). + + It is also possible to refer to entities that are not in + scope in the current module, by giving the full qualified name + of the entity: + + +-- | The identifier 'M.T' is not in scope + + + If M.T is not otherwise in scope, + then Haddock will simply emit a link pointing to the entity + T exported from module M + (without checking to see whether either M + or M.T exist). + + To make life easier for documentation writers, a quoted + identifier is only interpreted as such if the quotes surround + a lexically valid Haskell identifier. This means, for + example, that it normally isn't necessary to escape the single + quote when used as an apostrophe: + + +-- | I don't have to escape my apostrophes; great, isn't it? + + + For compatibility with other systems, the following + alternative form of markup is accepted + We chose not to use this as the primary markup for + identifiers because strictly speaking the ` + character should not be used as a left quote, it is a grave accent. + : `T'. +

+ +

+ Emphasis and Monospaced text + + Emphasis may be added by surrounding text with + /.../. + + Monospaced (or typewriter) text is indicated by + surrounding it with @...@. Other markup is + valid inside a monospaced span: for example + @'f' a b@ will hyperlink the + identifier f inside the code fragment. +

+ +

+ 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 + +

+ +

+ Definition lists + + Definition lists are written as follows: + + +-- | This is a definition list: +-- +-- [@foo@] The description of @foo@. +-- +-- [@bar@] The description of @bar@. + + + To produce output something like this: + + + + foo + + The description of foo. + + + + bar + + The description of bar. + + + + + Each paragraph should be preceded by the + “definition term” enclosed in square brackets. + The square bracket characters have no special meaning outside + the beginning of a definition paragraph. That is, if a + paragraph begins with a [ character, then + it is assumed to be a definition paragraph, and the next + ] character found will close the definition + term. Other markup operators may be used freely within the + definition term. +

+ +

+ 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. +

+ +

+ Anchors + + Sometimes it is useful to be able to link to a point in + the documentation which doesn't correspond to a particular + entity. For that purpose, we allow anchors to be + included in a documentation comment. The syntax is + #label#, where + label is the name of the anchor. + An anchor is invisible in the generated documentation. + + To link to an anchor from elsewhere, use the syntax + "module#label" + where module is the module name + containing the anchor, and label is + the anchor label. The module does not have to be local, it + can be imported via an interface. +

+ + }