codesnippets:haddockexamples
Differences
This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
| codesnippets:haddockexamples [2021/03/15 22:44] – [Controlling the documentation structure] f2b216 | codesnippets:haddockexamples [2025/10/08 00:48] (current) – external edit 127.0.0.1 | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== Haddock examples ====== | ====== Haddock examples ====== | ||
| - | |||
| ===== Markups ===== | ===== Markups ===== | ||
| Line 22: | Line 21: | ||
| ==== Code Blocks ==== | ==== Code Blocks ==== | ||
| - | < | + | < |
| -- | This documentation includes two blocks of code: | -- | This documentation includes two blocks of code: | ||
| -- | -- | ||
| Line 34: | Line 33: | ||
| ==== Examples ==== | ==== Examples ==== | ||
| - | < | + | < |
| -- | Two examples are given below: | -- | Two examples are given below: | ||
| -- | -- | ||
| Line 47: | Line 46: | ||
| ==== Properties ==== | ==== Properties ==== | ||
| - | < | + | < |
| -- | Addition is commutative: | -- | Addition is commutative: | ||
| -- | -- | ||
| Line 55: | Line 54: | ||
| ==== Hyperlinked Identifiers ==== | ==== Hyperlinked Identifiers ==== | ||
| - | < | + | < |
| -- | This module defines the type ' | -- | This module defines the type ' | ||
| </ | </ | ||
| - | < | + | < |
| -- | The identifier ' | -- | The identifier ' | ||
| </ | </ | ||
| - | < | + | < |
| -- | I don't have to escape my apostrophes; | -- | I don't have to escape my apostrophes; | ||
| </ | </ | ||
| Line 81: | Line 80: | ||
| Bold (strong) text is indicated by surrounding it with... | Bold (strong) text is indicated by surrounding it with... | ||
| - | < | + | < |
| Other markup is valid inside bold. For example ... | Other markup is valid inside bold. For example ... | ||
| - | < | + | < |
| ...will make the emphasised text foo bold. | ...will make the emphasised text foo bold. | ||
| Line 91: | Line 90: | ||
| You don't have to escape a single underscore if you need it bold... | You don't have to escape a single underscore if you need it bold... | ||
| - | < | + | < |
| Monospaced (or typewriter) text is indicated by surrounding it with | Monospaced (or typewriter) text is indicated by surrounding it with | ||
| Line 105: | Line 104: | ||
| ==== Linking to modules ==== | ==== Linking to modules ==== | ||
| - | < | + | < |
| -- | This is a reference to the " | -- | This is a reference to the " | ||
| </ | </ | ||
| Line 111: | Line 110: | ||
| ==== Itemized and enumerated lists ==== | ==== Itemized and enumerated lists ==== | ||
| - | < | + | < |
| -- | This is a bulleted list: | -- | This is a bulleted list: | ||
| -- | -- | ||
| Line 119: | Line 118: | ||
| </ | </ | ||
| - | < | + | < |
| -- | This is an enumerated list: | -- | This is an enumerated list: | ||
| -- | -- | ||
| Line 127: | Line 126: | ||
| </ | </ | ||
| - | < | + | < |
| -- | This is an enumerated list: | -- | This is an enumerated list: | ||
| -- | -- | ||
| Line 139: | Line 138: | ||
| </ | </ | ||
| - | < | + | < |
| -- | | -- | | ||
| -- * first item | -- * first item | ||
| Line 147: | Line 146: | ||
| </ | </ | ||
| - | < | + | < |
| {-| | {-| | ||
| * Beginning of list | * Beginning of list | ||
| Line 174: | Line 173: | ||
| ==== Definition lists ==== | ==== Definition lists ==== | ||
| - | < | + | < |
| -- | This is a definition list: | -- | This is a definition list: | ||
| -- | -- | ||
| Line 209: | Line 208: | ||
| ==== Headings ==== | ==== Headings ==== | ||
| - | < | + | < |
| -- | | -- | | ||
| -- = Heading level 1 with some __bold__ | -- = Heading level 1 with some __bold__ | ||
| Line 221: | Line 220: | ||
| </ | </ | ||
| - | < | + | < |
| -- | | -- | | ||
| -- = Heading level 1 with some __bold__ | -- = Heading level 1 with some __bold__ | ||
| Line 238: | Line 237: | ||
| ==== simple ==== | ==== simple ==== | ||
| - | < | + | < |
| -- |The ' | -- |The ' | ||
| square :: Int -> Int | square :: Int -> Int | ||
| Line 246: | Line 245: | ||
| ==== after the declaration ==== | ==== after the declaration ==== | ||
| - | < | + | < |
| square :: Int -> Int | square :: Int -> Int | ||
| -- ^The ' | -- ^The ' | ||
| Line 254: | Line 253: | ||
| ==== several lines ==== | ==== several lines ==== | ||
| - | < | + | < |
| -- |The ' | -- |The ' | ||
| -- It takes one argument, of type ' | -- It takes one argument, of type ' | ||
| Line 263: | Line 262: | ||
| ==== nested-comment style ==== | ==== nested-comment style ==== | ||
| - | < | + | < |
| {-| | {-| | ||
| The ' | The ' | ||
| Line 274: | Line 273: | ||
| ===== Class methods ===== | ===== Class methods ===== | ||
| - | < | + | < |
| class C a where | class C a where | ||
| -- | This is the documentation for the ' | -- | This is the documentation for the ' | ||
| Line 284: | Line 283: | ||
| ===== Constructors and record fields ===== | ===== Constructors and record fields ===== | ||
| - | < | + | < |
| data T a b | data T a b | ||
| -- | This is the documentation for the ' | -- | This is the documentation for the ' | ||
| Line 292: | Line 291: | ||
| </ | </ | ||
| - | < | + | < |
| data T a b | data T a b | ||
| = C1 a b -- ^ This is the documentation for the ' | = C1 a b -- ^ This is the documentation for the ' | ||
| Line 298: | Line 297: | ||
| </ | </ | ||
| - | < | + | < |
| data R a b = | data R a b = | ||
| C { -- | This is the documentation for the ' | C { -- | This is the documentation for the ' | ||
| Line 307: | Line 306: | ||
| </ | </ | ||
| - | < | + | < |
| data R a b = | data R a b = | ||
| C { a :: a -- ^ This is the documentation for the ' | C { a :: a -- ^ This is the documentation for the ' | ||
| Line 314: | Line 313: | ||
| </ | </ | ||
| - | < | + | < |
| data T a = A { someField :: a -- ^ Doc for someField of A | data T a = A { someField :: a -- ^ Doc for someField of A | ||
| } | } | ||
| Line 323: | Line 322: | ||
| ===== Function arguments ===== | ===== Function arguments ===== | ||
| - | < | + | < |
| f :: Int -- ^ The ' | f :: Int -- ^ The ' | ||
| -> Float -- ^ The ' | -> Float -- ^ The ' | ||
| Line 331: | Line 330: | ||
| ===== The module description ===== | ===== The module description ===== | ||
| - | < | + | < |
| {-| | {-| | ||
| Module | Module | ||
| Line 353: | 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, | 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, | ||
| - | < | + | < |
| module Foo ( | module Foo ( | ||
| -- * Classes | -- * Classes | ||
| Line 369: | Line 368: | ||
| Alternativerly with commas at the beginning. | Alternativerly with commas at the beginning. | ||
| - | < | + | < |
| module Foo ( | module Foo ( | ||
| -- * Classes | -- * Classes | ||
| Line 388: | 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. | ||
| - | < | + | < |
| module A ( | module A ( | ||
| module B, | module B, | ||
| Line 397: | Line 396: | ||
| If the modules are not completely re-exported, | If the modules are not completely re-exported, | ||
| - | < | + | < |
| module A ( | module A ( | ||
| module B, | module B, | ||
| Line 411: | 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. | ||
| - | < | + | < |
| module Foo where | module Foo where | ||
| </ | </ | ||
| Line 417: | Line 416: | ||
| And the module body __may__ also include section headings. | And the module body __may__ also include section headings. | ||
| - | < | + | < |
| module Foo where | module Foo where | ||
| Line 433: | Line 432: | ||
| The documentation can be included in the export list directly. | The documentation can be included in the export list directly. | ||
| - | < | + | < |
| module Foo ( | module Foo ( | ||
| -- * A section heading | -- * A section heading | ||
| Line 444: | Line 443: | ||
| 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. | 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 ( | module Foo ( | ||
| -- * A section heading | -- * A section heading | ||
| Line 466: | Line 465: | ||
| * A module with the not-home attribute is only chosen if there are no other modules to choose. | * A module with the not-home attribute is only chosen if there are no other modules to choose. | ||
| - | < | + | < |
| module A (T) where | module A (T) where | ||
| data T a = C a | data T a = C a | ||
| Line 488: | Line 487: | ||
| Attributes are specified in a comma-separated list in an {-# OPTIONS_HADDOCK ... #-} pragma at the top of the module. | 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 #-} | {-# OPTIONS_HADDOCK hide, prune, ignore-exports #-} | ||
| Line 542: | Line 541: | ||
| </ | </ | ||
| + | |||
| + | ===== ✎ ===== | ||
| + | ~~DISCUSSION~~ | ||
codesnippets/haddockexamples.1615844669.txt.gz · Last modified: (external edit)