====== Haddock examples ======

===== Markups =====

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

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.

==== Character references ====

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.

==== Code Blocks ====

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

==== Examples ====

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

==== Properties ====

<code Haskell>
-- | Addition is commutative:
--
-- prop> a + b = b + a
</code>

==== Hyperlinked Identifiers ====

<code Haskell>
-- | This module defines the type 'T'.
</code>

<code Haskell>
-- | The identifier 'M.T' is not in scope
</code>

<code Haskell>
-- | I don't have to escape my apostrophes; great, isn't it?
</code>

==== Emphasis, bold and monospaced text ====

Emphasis may be added by surrounding text with...

<code>/.../</code>

Other markup is valid inside emphasis.

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

<code>/fo\/o/</code>

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

<code Haskell>__...__</code>

Other markup is valid inside bold. For example ...

<code Haskell>__/foo/__</code>

...will make the emphasised text foo bold.

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

<code Haskell>__This_text_with_underscores_is_bold__</code>

Monospaced (or typewriter) text is indicated by surrounding it with

<code>@...@</code>

Other markup is valid inside a monospaced span: for example...

<code>@'f' a b@</code>

...will hyperlink the identifier f inside the code fragment

==== Linking to modules ====

<code Haskell>
-- | This is a reference to the "Foo" module.
</code>

==== Itemized and enumerated lists ====

<code Haskell>
-- | This is a bulleted list:
--
--     * first item
--
--     * second item
</code>

<code Haskell>
-- | This is an enumerated list:
--
--     (1) first item
--
--     2. second item
</code>

<code Haskell>
-- | This is an enumerated list:
--
--     (1) first item
--     2. second item
--
-- This is a bulleted list:
--
--     * first item
--     * second item
</code>

<code Haskell>
-- |
-- * first item
-- and more content for the first item
-- * second item
-- and more content for the second item
</code>

<code Haskell>
{-|
* 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.
-}
</code>

==== Definition lists ====

<code Haskell>
-- | This is a definition list:
--
--   [@foo@] The description of @foo@.
--
--   [@bar@] The description of @bar@.
</code>

To produce output something like this:

''foo''
  * The description of ''foo''.
''bar''
  * The description of ''bar''.

==== URLs ====

<code>
<http://example.com label>
</code>

==== Images ====

<code>
<<pathtoimage.png title>>
</code>

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

==== Headings ====

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

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


===== Documenting a top-level declaration =====

==== simple ====

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

==== after the declaration ====

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

==== several lines ====

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

==== nested-comment style ====

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

===== Class methods =====

<code Haskell>
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
</code>

===== Constructors and record fields =====

<code Haskell>
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
</code>

<code Haskell>
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
</code>

<code Haskell>
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
    }
</code>

<code Haskell>
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
    }
</code>

<code Haskell>
data T a = A { someField :: a -- ^ Doc for someField of A
             }
         | B { someField :: a -- ^ Doc for someField of B
             }
</code>

===== Function arguments =====

<code Haskell>
f  :: Int      -- ^ The 'Int' argument
   -> Float    -- ^ The 'Float' argument
   -> IO ()    -- ^ The return value
</code>

===== The module description =====

<code Haskell>
{-|
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
...
</code>

===== Controlling the documentation structure =====

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.

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

Alternativerly with commas at the beginning.

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

===== Re-exporting an entire module =====

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. 

<code Haskell>
module A (
  module B,
  module C
 ) where
</code>

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.

<code Haskell>
module A (
  module B,
  module C
 ) where

import B hiding (f)
import C (a, b)
</code>

===== Omitting the export list =====

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.

<code Haskell>
module Foo where
</code>

And the module body __may__ also include section headings.

<code Haskell>
module Foo where

-- * This heading will now appear before foo.

-- | Documentation for 'foo'.
foo :: Integer
foo = 5
</code>

===== Named chunks of documentation =====

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.

<code Haskell>
module Foo (
   -- * A section heading

   -- | Some documentation not attached to a particular Haskell entity
   ...
 ) where
</code>

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.

<code Haskell>
module Foo (
   -- * A section heading

   -- $doc
   ...
 ) where

-- $doc
-- Here is a large chunk of documentation which may be referred to by
-- the name $doc.
</code>

===== Hyperlinking and re-exported entities =====

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.

<code Haskell>
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
</code>

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.

===== Module Attributes =====

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

<code Haskell>
{-# OPTIONS_HADDOCK hide, prune, ignore-exports #-}

-- |Module description
module A where
...
</code>

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.


===== Acknowledgements =====

This cheat sheet used the achievements from
<WRAP center round box 60%>
  * **Simon Marlow**
  * **David Waern**
</WRAP>


===== Source =====

==== Haddock User Guide ====

  * [[https://www.haskell.org/haddock/doc/html/index.html|Haddock User Guide - Table of content]]
  * [[https://www.haskell.org/haddock/doc/html/markup.html|Haddock User Guide - Chapter 3. Documentation and Markup]]
  * [[https://www.haskell.org/haddock/doc/html/license.html|License]]


===== License =====

The following license covers **__this documentation__**, and the Haddock source code, except where otherwise indicated.

<WRAP center round box 60%>
Copyright 2002-2010, Simon Marlow. All rights reserved.
</WRAP>

<WRAP center round box 60%>
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.
</WRAP>

<WRAP center round box 60%>
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.
</WRAP>


===== ✎ =====
~~DISCUSSION~~