Haddock examples

One or more blank lines separates two paragraphs in a documentation comment.

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

Furthermore, the character sequence »> has a special meaning at the beginning of a line. To escape it, just prefix the characters in the sequence with a backslash.

Although Haskell source files may contain any character from the Unicode character set, the encoding of these characters as bytes varies between systems, so that only source files restricted to the ASCII character set are portable. Other characters may be specified in character and string literals using Haskell character escapes. To represent such characters in documentation comments, Haddock supports SGML-style numeric character references of the forms &#D; and &#xH; where D and H are decimal and hexadecimal numbers denoting a code position in Unicode (or ISO 10646). For example, the references &#x3BB;, &#x3bb; and &#955; all represent the lower-case letter lambda.

-- | This documentation includes two blocks of code:
--
-- @
--     f x = x + x
-- @
--
-- >  g x = x * 42

-- | Two examples are given below:
--
-- >>> fib 10
-- 55
--
-- >>> putStrLn "foo\nbar"
-- foo
-- bar

-- | Addition is commutative:
--
-- prop> a + b = b + a

-- | This module defines the type 'T'.

-- | The identifier 'M.T' is not in scope

-- | I don't have to escape my apostrophes; great, isn't it?

Emphasis may be added by surrounding text with…

/.../

Other markup is valid inside emphasis.

To have a forward slash inside of emphasis, just escape it…

/fo\/o/

Bold (strong) text is indicated by surrounding it with…

__...__

Other markup is valid inside bold. For example …

__/foo/__

…will make the emphasised text foo bold.

You don't have to escape a single underscore if you need it bold…

__This_text_with_underscores_is_bold__

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

-- | This is a reference to the "Foo" module.

-- | This is a bulleted list:
--
--     * first item
--
--     * second item

-- | This is an enumerated list:
--
--     (1) first item
--
--     2. second item

-- | This is an enumerated list:
--
--     (1) first item
--     2. second item
--
-- This is a bulleted list:
--
--     * first item
--     * second item

-- |
-- * first item
-- and more content for the first item
-- * second item
-- and more content for the second item

{-|
* Beginning of list
This belongs to the list above!
 
    > nested
    > bird
    > tracks
 
    * Next list
    More of the indented list.
 
        * Deeper
 
            @
            even code blocks work
            @
 
            * Deeper
 
                    1. Even deeper!
                    2. No newline separation even in indented lists.
-}

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

<http://example.com label>

<<pathtoimage.png title>>

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. Please note that in Haddock versions 2.13.x and earlier, the syntax was “module\#label”. It is considered deprecated and will be removed in the future.

-- |
-- = Heading level 1 with some __bold__
-- Something underneath the heading.
--
-- == /Subheading/
-- More content.
--
-- === Subsubheading
-- Even more content.

-- |
-- = Heading level 1 with some __bold__
-- Something underneath the heading.
--
-- == /Subheading/
-- More content.
--
-- === Subsubheading
-- >>> examples are only allowed at the start of paragraphs

-- |The 'square' function squares an integer.
square :: Int -> Int
square x = x * x

square :: Int -> Int
-- ^The 'square' function squares an integer.
square x = x * x

-- |The 'square' function squares an integer.
-- It takes one argument, of type 'Int'.
square :: Int -> Int
square x = x * x

{-|
  The 'square' function squares an integer.
  It takes one argument, of type 'Int'.
-}
square :: Int -> Int
square x = x * x

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

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

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

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
    }

data T a = A { someField :: a -- ^ Doc for someField of A
             }
         | B { someField :: a -- ^ Doc for someField of B
             }

f  :: Int      -- ^ The 'Int' argument
   -> Float    -- ^ The 'Float' argument
   -> IO ()    -- ^ The return value

{-|
Module      : W
Description : Short description
Copyright   : (c) Some Guy, 2013
                  Someone Else, 2014
License     : GPL-3
Maintainer  : sample@email.com
Stability   : experimental
Portability : POSIX
 
Here is a longer description of this module, containing some
commentary with @some markup@.
-}
module W where
...

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.

module Foo (
  -- * Classes
  C(..),
  -- * Types
  -- ** A data type
  T,
  -- ** A record
  R,
  -- * Some functions
  f, g
  ) where

Alternativerly with commas at the beginning.

module Foo (
  -- * Classes
  , C(..)
  -- * Types
  -- ** A data type
  , T
  -- ** A record
  , R
  -- * Some functions
  , f
  , g
  ) where

If modules are imported wholly and without any hiding qualifiers, then the documentation will just contain a cross-reference to the documentation for B and C.

module A (
  module B,
  module C
 ) where

If the modules are not completely re-exported, then Haddock behaves as if the set of entities re-exported from B and C had been listed explicitly in the export list.

module A (
  module B,
  module C
 ) where
 
import B hiding (f)
import C (a, b)

If there is no export list in the module, then every entity will be mentioned as defined at the top level in the module. The generated documentation will retain the order in which entities are defined in the module.

module Foo where

And the module body may also include section headings.

module Foo where
 
-- * This heading will now appear before foo.
 
-- | Documentation for 'foo'.
foo :: Integer
foo = 5

To include a chunk of documentation which is not attached to any particular Haskell declaration.

The documentation can be included in the export list directly.

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.

module Foo (
   -- * A section heading
 
   -- $doc
   ...
 ) where
 
-- $doc
-- Here is a large chunk of documentation which may be referred to by
-- the name $doc.

Haddock takes the view that each entity has a home module; that is, the module that the library designer would most like to direct the user to, to find the documentation for that entity. So, Haddock makes all links to an entity point to the home module. The one exception is when the entity is also exported by the current module: Haddock makes a local link if it can.

Haddock uses the following rules:

• If modules A and B both export the entity, and module A imports (directly or indirectly) module B, then B is preferred.
• A module with the hide attribute is never chosen as the home.
• A module with the not-home attribute is only chosen if there are no other modules to choose.

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

If multiple modules fit the criteria, then one is chosen at random. If no modules fit the criteria (because the candidates are all hidden), then Haddock will issue a warning for each reference to an entity without a home.

In the example above, module A is chosen as the home for T because it does not import any other module that exports T. The link from f's type in module B will therefore point to A.T. However, C also exports T and f, and the link from f's type in C will therefore point locally to C.T.

Attributes are specified in a comma-separated list in an {-# OPTIONS_HADDOCK … #-} pragma at the top of the module.

{-# OPTIONS_HADDOCK hide, prune, ignore-exports #-}
 
-- |Module description
module A where
...

The following attributes are currently understood by Haddock:

• 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: Omit definitions that have no documentation annotations from the generated documentation.
• 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.
• not-home: Indicates that the current module should not be considered to be the home module for each entity it exports, unless that entity is not exported from any other module. See Section 3.6, “Hyperlinking and re-exported entities” for more details.
• show-extensions: Indicates that we should render the extensions used in this module in the resulting documentation. This will only render if the output format supports it. If Language is set, it will be shown as well and all the extensions implied by it won't. All enabled extensions will be rendered, including those implied by their more powerful versions.

This cheat sheet used the achievements from

• Haddock User Guide - Table of content
• Haddock User Guide - Chapter 3. Documentation and Markup
• License

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