From 68c34f065a0a26b07e5cadb7ddd91e833623433f Mon Sep 17 00:00:00 2001 From: panne Date: Mon, 16 Aug 2004 19:59:38 +0000 Subject: [haddock @ 2004-08-16 19:59:36 by panne] XMLification --- doc/haddock.xml | 1437 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1437 insertions(+) create mode 100644 doc/haddock.xml (limited to 'doc/haddock.xml') diff --git a/doc/haddock.xml b/doc/haddock.xml new file mode 100644 index 00000000..b0592eb9 --- /dev/null +++ b/doc/haddock.xml @@ -0,0 +1,1437 @@ + + + + + + 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. +
+
+ + -- cgit v1.2.3