From bdd3be0b9f98f15ca5ae6e6b1ea808ab9991448d Mon Sep 17 00:00:00 2001 From: simonmar Date: Thu, 9 May 2002 15:59:56 +0000 Subject: [haddock @ 2002-05-09 15:59:56 by simonmar] Document changes since 0.1 --- doc/haddock.sgml | 178 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 149 insertions(+), 29 deletions(-) (limited to 'doc') diff --git a/doc/haddock.sgml b/doc/haddock.sgml index 959e396a..2564a14b 100644 --- a/doc/haddock.sgml +++ b/doc/haddock.sgml @@ -421,6 +421,30 @@ square x = x * x 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 @@ -591,18 +615,45 @@ module Foo ( list: -module Foo ( - module Bar, - module Baz +module A ( + module B, + module C ) where What will the Haddock-generated documentation for this - module look like? Well, Haddock simply behaves as if the - export list for modules Bar and - Baz had been expanded in-place in the - export list for Foo, including all of their - structure (section headings etc.). + 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.
@@ -639,6 +690,7 @@ module Foo ( module Foo ( -- * A section heading + -- | Some documentation not attached to a particular Haskell entity ... ) where @@ -656,6 +708,7 @@ module Foo ( module Foo ( -- * A section heading + -- $doc ... ) where @@ -742,6 +795,61 @@ import B
+
+ 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. + + + + + prune + hide + + Omit definitions that have no documentation + annotations from the generated documentation. + + + + + ignore-exports + hide + + 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 @@ -764,42 +872,34 @@ import B The following characters have special meanings in documentation comments: /, - ', [, - ], <. To insert a - literal occurrence of one of these special characters, precede - it with a backslash (\). - - Additionally, the following characters have special - meanings at the beginning of a paragraph: + ', `, + ", @, + <. 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 \. - -
- -
- Emphasis and Monospaced text - - Emphasis may be added by surrounding text with - /.../. - - Monospaced (or typewriter) text is indicated by - surrounding it with [...].
Code Blocks Displayed blocks of code are indicated by surrounding a - paragraph with [...] or by preceding each + paragraph with @...@ or by preceding each line of a paragraph with >. For example: -- | This documentation includes two blocks of code: -- --- [ +-- @ -- f x = x + x --- ] +-- @ -- -- > g x = x * 42 @@ -822,6 +922,26 @@ import B T (if the output format supports hyperlinking, of course; in a printed format it might instead insert a page reference to the definition). + + 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.
-- cgit v1.2.3