diff options
| author | Luke Lau <luke_lau@icloud.com> | 2020-05-22 17:34:57 +0100 |
|---|---|---|
| committer | Ben Gamari <ben@smart-cactus.org> | 2021-03-10 15:55:09 -0500 |
| commit | 8a59f49ae2204dbf58ef50ea8c0a50ee2c7aa64a (patch) | |
| tree | be7327cba2bc8b2d3187baebb92986a20e61d7af /docs | |
| parent | e687ba83b0506bc800ceb79e6ee8cb0f8ed31ed6 (diff) | |
| download | haskell-8a59f49ae2204dbf58ef50ea8c0a50ee2c7aa64a.tar.gz | |
template-haskell: Add putDoc, getDoc, withDecDoc and friends
This adds two new methods to the Quasi class, putDoc and getDoc. They
allow Haddock documentation to be added to declarations, module headers,
function arguments and class/type family instances, as well as looked
up.
It works by building up a map of names to attach pieces of
documentation to, which are then added in the extractDocs function in
GHC.HsToCore.Docs. However because these template haskell names need to
be resolved to GHC names at the time they are added, putDoc cannot
directly add documentation to declarations that are currently being
spliced. To remedy this, withDecDoc/withDecsDoc wraps the operation with
addModFinalizer, and provides a more ergonomic interface for doing so.
Similarly, the funD_doc, dataD_doc etc. combinators provide a more
ergonomic interface for documenting functions and their arguments
simultaneously.
This also changes ArgDocMap to use an IntMap rather than an Map Int, for
efficiency.
Part of the work towards #5467
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/users_guide/9.2.1-notes.rst | 13 |
1 files changed, 13 insertions, 0 deletions
diff --git a/docs/users_guide/9.2.1-notes.rst b/docs/users_guide/9.2.1-notes.rst index 3b0022fb8a..131f694f6b 100644 --- a/docs/users_guide/9.2.1-notes.rst +++ b/docs/users_guide/9.2.1-notes.rst @@ -165,6 +165,19 @@ Runtime system is returned is controlled by the :rts-flag:`-Fd ⟨factor⟩`. Memory return is triggered by consecutive idle collections. +Template Haskell +~~~~~~~~~~~~~~~~ + +- There are two new functions ``putDoc`` and ``getDoc``, which allow Haddock + documentation to be attached and read from module headers, declarations, + function arguments, class instances and family instances. + These functions are quite low level, so the ``withDecDoc`` function provides + a more ergonomic interface for this. Similarly ``funD_doc``, ``dataD_doc`` + and friends provide an easy way to document functions and constructors + alongside their arguments simultaneously. :: + + $(withDecsDoc "This does good things" [d| foo x = 42 |]) + ``ghc-prim`` library ~~~~~~~~~~~~~~~~~~~~ |