HaskSheet

User Tools

Site Tools

Trace: • accumulatingwithinmonadiccontextswithoutfolds • statemonads • applicative • letandwhereconstructs • parametrictypeforanintermediatevaluewhencombiningfunctions • background • prelude
codesnippets:haddockexamples

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
codesnippets:haddockexamples [2021/03/12 09:46] – created f2b216codesnippets:haddockexamples [2025/10/08 00:48] (current) – external edit 127.0.0.1
Line 1: Line 1:
 ====== Haddock examples ====== ====== 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 ===== ===== Documenting a top-level declaration =====
Line 5: Line 237:
 ==== simple ==== ==== simple ====
  
-<code>+<code Haskell>
 -- |The 'square' function squares an integer. -- |The 'square' function squares an integer.
 square :: Int -> Int square :: Int -> Int
Line 13: Line 245:
 ==== after the declaration ==== ==== after the declaration ====
  
-<code>+<code Haskell>
 square :: Int -> Int square :: Int -> Int
 -- ^The 'square' function squares an integer. -- ^The 'square' function squares an integer.
Line 21: Line 253:
 ==== several lines ==== ==== several lines ====
  
-<code>+<code Haskell>
 -- |The 'square' function squares an integer. -- |The 'square' function squares an integer.
 -- It takes one argument, of type 'Int'. -- It takes one argument, of type 'Int'.
Line 30: Line 262:
 ==== nested-comment style ==== ==== nested-comment style ====
  
-<code>+<code Haskell>
 {-| {-|
   The 'square' function squares an integer.   The 'square' function squares an integer.
Line 41: Line 273:
 ===== Class methods ===== ===== Class methods =====
  
-<code>+<code Haskell>
 class C a where class C a where
    -- | This is the documentation for the 'f' method    -- | This is the documentation for the 'f' method
Line 51: Line 283:
 ===== Constructors and record fields ===== ===== Constructors and record fields =====
  
-<code>+<code Haskell>
 data T a b data T a b
   -- | This is the documentation for the 'C1' constructor   -- | This is the documentation for the 'C1' constructor
Line 59: Line 291:
 </code> </code>
  
-<code>+<code Haskell>
 data T a b data T a b
   = C1 a b  -- ^ This is the documentation for the 'C1' constructor   = C1 a b  -- ^ This is the documentation for the 'C1' constructor
Line 65: Line 297:
 </code> </code>
  
-<code>+<code Haskell>
 data R a b = data R a b =
   C { -- | This is the documentation for the 'a' field   C { -- | This is the documentation for the 'a' field
Line 74: Line 306:
 </code> </code>
  
-<code>+<code Haskell>
 data R a b = data R a b =
   C { a :: a  -- ^ This is the documentation for the 'a' field   C { a :: a  -- ^ This is the documentation for the 'a' field
Line 81: Line 313:
 </code> </code>
  
-<code>+<code Haskell>
 data T a = A { someField :: a -- ^ Doc for someField of A data T a = A { someField :: a -- ^ Doc for someField of A
              }              }
Line 90: Line 322:
 ===== Function arguments ===== ===== Function arguments =====
  
-<code>+<code Haskell>
 f  :: Int      -- ^ The 'Int' argument f  :: Int      -- ^ The 'Int' argument
    -> Float    -- ^ The 'Float' argument    -> Float    -- ^ The 'Float' argument
Line 98: Line 330:
 ===== The module description ===== ===== The module description =====
  
-<code>+<code Haskell>
 {-| {-|
 Module      : W Module      : W
Line 120: Line 352:
 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. 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>+<code Haskell>
 module Foo ( module Foo (
   -- * Classes   -- * Classes
Line 134: Line 366:
 </code> </code>
  
-<code>+Alternativerly with commas at the beginning. 
 + 
 +<code Haskell>
 module Foo ( module Foo (
   -- * Classes   -- * Classes
Line 153: Line 387:
 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.  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>+<code Haskell>
 module A ( module A (
   module B,   module B,
Line 162: Line 396:
 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. 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>+<code Haskell>
 module A ( module A (
   module B,   module B,
Line 176: Line 410:
 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. 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>+<code Haskell>
 module Foo where module Foo where
 </code> </code>
Line 182: Line 416:
 And the module body __may__ also include section headings. And the module body __may__ also include section headings.
  
-<code>+<code Haskell>
 module Foo where module Foo where
  
Line 194: Line 428:
 ===== Named chunks of documentation ===== ===== Named chunks of documentation =====
  
-<code>+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 ( module Foo (
    -- * A section heading    -- * A section heading
Line 203: Line 441:
 </code> </code>
  
-<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 ( module Foo (
    -- * A section heading    -- * A section heading
Line 216: Line 456:
 </code> </code>
  
-<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> </code>
  
-<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> </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.
  
  
Line 234: Line 514:
 ===== Source ===== ===== Source =====
  
-  * [[https://www.haskell.org/haddock/doc/html/markup.html|Haddock User Guide - Chapter 3. Documentation and Markup]]+==== 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/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]]   * [[https://www.haskell.org/haddock/doc/html/license.html|License]]
 +
  
 ===== License ===== ===== License =====
Line 258: Line 541:
 </WRAP> </WRAP>
  
 +
 +===== ✎ =====
 +~~DISCUSSION~~
codesnippets/haddockexamples.1615538760.txt.gz · Last modified: (external edit)
Except where otherwise noted, content on this wiki is licensed under the following license: CC0 1.0 Universal
CC0 1.0 Universal Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki