[[haddock @ 2002-05-09 15:59:56 by simonmar]
simonmar**20020509155956
Document changes since 0.1
] {
hunk ./doc/haddock.sgml 424
+ 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
+
+
hunk ./doc/haddock.sgml 618
-module Foo (
- module Bar,
- module Baz
+module A (
+ module B,
+ module C
hunk ./doc/haddock.sgml 625
- 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.
hunk ./doc/haddock.sgml 693
+
hunk ./doc/haddock.sgml 711
+
hunk ./doc/haddock.sgml 796
+
+
+
+ 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.
+
+
+
hunk ./doc/haddock.sgml 875
- ', [,
- ], <. To insert a
- literal occurrence of one of these special characters, precede
- it with a backslash (\).
+ ', `,
+ ", @,
+ <. To insert a literal occurrence of
+ one of these special characters, precede it with a backslash
+ (\).
hunk ./doc/haddock.sgml 881
- Additionally, the following characters have special
- meanings at the beginning of a paragraph:
+ 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:
hunk ./doc/haddock.sgml 887
-
-
-
-
- Emphasis and Monospaced text
-
- Emphasis may be added by surrounding text with
- /.../.
-
- Monospaced (or typewriter) text is indicated by
- surrounding it with [...].
hunk ./doc/haddock.sgml 893
- paragraph with [...] or by preceding each
+ paragraph with @...@ or by preceding each
hunk ./doc/haddock.sgml 900
--- [
+-- @
hunk ./doc/haddock.sgml 902
--- ]
+-- @
hunk ./doc/haddock.sgml 925
+
+ 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.
}