diff options
Diffstat (limited to 'doc/haddock.xml')
| -rw-r--r-- | doc/haddock.xml | 2329 |
1 files changed, 0 insertions, 2329 deletions
diff --git a/doc/haddock.xml b/doc/haddock.xml deleted file mode 100644 index e805a437..00000000 --- a/doc/haddock.xml +++ /dev/null @@ -1,2329 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ - <!ENTITY nbsp ' '> - <!ENTITY frac12 '½'> - <!ENTITY mdash '—'> - <!ENTITY lsquo '’'> - <!ENTITY rsquo '‚'> - <!ENTITY ldquo '“'> - <!ENTITY rdquo '”'> -] > - -<book id="haddock"> - <bookinfo> - <date>2015-06-02</date> - <title>Haddock User Guide</title> - <author> - <firstname>Simon</firstname> - <surname>Marlow</surname> - </author> - <address><email>marlowsd@gmail.com</email></address> - <author> - <firstname>David</firstname> - <surname>Waern</surname> - </author> - <address><email>david.waern@gmail.com</email></address> - <author> - <firstname>Mateusz</firstname> - <surname>Kowalczyk</surname> - </author> - <address><email>fuuzetsu@fuuzetsu.co.uk</email></address> - <copyright> - <year>2010</year> - <holder>Simon Marlow, David Waern</holder> - </copyright> - <copyright> - <year>2013-2015</year> - <holder>Mateusz Kowalczyk</holder> - </copyright> - <abstract> - <para>This document describes Haddock version 2.16.2, a Haskell - documentation tool.</para> - </abstract> - </bookinfo> - - <!-- Table of contents --> - <toc></toc> - - <chapter id="introduction"> - <title>Introduction</title> - - <para>This is Haddock, a tool for automatically generating - documentation from annotated Haskell source code. Haddock was - designed with several goals in mind:</para> - - <itemizedlist> - <listitem> - <para>When documenting APIs, it is desirable to keep the - documentation close to the actual interface or implementation - of the API, preferably in the same file, to reduce the risk - that the two become out of sync. Haddock therefore lets you - write the documentation for an entity (function, type, or - class) next to the definition of the entity in the source - code.</para> - </listitem> - <listitem> - <para>There is a tremendous amount of useful API documentation - that can be extracted from just the bare source code, - including types of exported functions, definitions of data - types and classes, and so on. Haddock can therefore generate - documentation from a set of straight Haskell 98 modules, and - the documentation will contain precisely the interface that is - available to a programmer using those modules.</para> - </listitem> - <listitem> - <para>Documentation annotations in the source code should be - easy on the eye when editing the source code itself, so as not - to obscure the code and to make reading and writing - documentation annotations easy. The easier it is to write - documentation, the more likely the programmer is to do it. - Haddock therefore uses lightweight markup in its annotations, - taking several ideas from <ulink - url="http://www.cse.unsw.edu.au/~chak/haskell/idoc/">IDoc</ulink>. - In fact, Haddock can understand IDoc-annotated source - code.</para> - </listitem> - <listitem> - <para>The documentation should not expose any of the structure - of the implementation, or to put it another way, the - implementer of the API should be free to structure the - implementation however he or she wishes, without exposing any - of that structure to the consumer. In practical terms, this - means that while an API may internally consist of several - Haskell modules, we often only want to expose a single module - to the user of the interface, where this single module just - re-exports the relevant parts of the implementation - modules.</para> - - <para>Haddock therefore understands the Haskell module system - and can generate documentation which hides not only - non-exported entities from the interface, but also the - internal module structure of the interface. A documentation - annotation can still be placed next to the implementation, and - it will be propagated to the external module in the generated - documentation.</para> - </listitem> - <listitem> - <para>Being able to move around the documentation by following - hyperlinks is essential. Documentation generated by Haddock - is therefore littered with hyperlinks: every type and class - name is a link to the corresponding definition, and - user-written documentation annotations can contain identifiers - which are linked automatically when the documentation is - generated.</para> - </listitem> - <listitem> - <para>We might want documentation in multiple formats - online - and printed, for example. Haddock comes with HTML, LaTeX, - and Hoogle backends, and it is structured in such a way that adding new - backends is straightforward.</para> - </listitem> - </itemizedlist> - - <section id="obtaining"> - <title>Obtaining Haddock</title> - - <para>Distributions (source & binary) of Haddock can be obtained - from its <ulink url="http://www.haskell.org/haddock/">web - site</ulink>.</para> - - <para>Up-to-date sources can also be obtained from our public - darcs repository. The Haddock sources are at - <literal>http://code.haskell.org/haddock</literal>. See - <ulink url="http://www.darcs.net/">darcs.net</ulink> for more - information on the darcs version control utility.</para> - </section> - - <section id="license"> - <title>License</title> - - <para>The following license covers this documentation, and the - Haddock source code, except where otherwise indicated.</para> - - <blockquote> - <para>Copyright 2002-2010, Simon Marlow. All rights reserved.</para> - - <para>Redistribution and use in source and binary forms, with - or without modification, are permitted provided that the - following conditions are met:</para> - - <itemizedlist> - <listitem> - <para>Redistributions of source code must retain the above - copyright notice, this list of conditions and the - following disclaimer.</para> - </listitem> - <listitem> - <para>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.</para> - </listitem> - </itemizedlist> - - <para>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.</para> - </blockquote> - </section> - - <section> - <title>Contributors</title> - <para>Haddock was originally written by Simon Marlow. Since it is an open source - project, many people have contributed to its development over the years. - Below is a list of contributors in alphabetical order that we hope is - somewhat complete. If you think you are missing from this list, please contact - us. - </para> - <itemizedlist> - <listitem><simpara>Ashley Yakeley</simpara></listitem> - <listitem><simpara>Benjamin Franksen</simpara></listitem> - <listitem><simpara>Brett Letner</simpara></listitem> - <listitem><simpara>Clemens Fruhwirth</simpara></listitem> - <listitem><simpara>Conal Elliott</simpara></listitem> - <listitem><simpara>David Waern</simpara></listitem> - <listitem><simpara>Duncan Coutts</simpara></listitem> - <listitem><simpara>George Pollard</simpara></listitem> - <listitem><simpara>George Russel</simpara></listitem> - <listitem><simpara>Hal Daume</simpara></listitem> - <listitem><simpara>Ian Lynagh</simpara></listitem> - <listitem><simpara>Isaac Dupree</simpara></listitem> - <listitem><simpara>Joachim Breitner</simpara></listitem> - <listitem><simpara>Krasimir Angelov</simpara></listitem> - <listitem><simpara>Lennart Augustsson</simpara></listitem> - <listitem><simpara>Luke Plant</simpara></listitem> - <listitem><simpara>Malcolm Wallace</simpara></listitem> - <listitem><simpara>Manuel Chakravarty</simpara></listitem> - <listitem><simpara>Mark Lentczner</simpara></listitem> - <listitem><simpara>Mark Shields</simpara></listitem> - <listitem><simpara>Mateusz Kowalczyk</simpara></listitem> - <listitem><simpara>Mike Thomas</simpara></listitem> - <listitem><simpara>Neil Mitchell</simpara></listitem> - <listitem><simpara>Oliver Brown</simpara></listitem> - <listitem><simpara>Roman Cheplyaka</simpara></listitem> - <listitem><simpara>Ross Paterson</simpara></listitem> - <listitem><simpara>Sigbjorn Finne</simpara></listitem> - <listitem><simpara>Simon Hengel</simpara></listitem> - <listitem><simpara>Simon Marlow</simpara></listitem> - <listitem><simpara>Simon Peyton-Jones</simpara></listitem> - <listitem><simpara>Stefan O'Rear</simpara></listitem> - <listitem><simpara>Sven Panne</simpara></listitem> - <listitem><simpara>Thomas Schilling</simpara></listitem> - <listitem><simpara>Wolfgang Jeltsch</simpara></listitem> - <listitem><simpara>Yitzchak Gale</simpara></listitem> - </itemizedlist> - </section> - <section> - <title>Acknowledgements</title> - - <para>Several documentation systems provided the inspiration for - Haddock, most notably:</para> - - <itemizedlist> - <listitem> - <para><ulink - url="http://www.cse.unsw.edu.au/~chak/haskell/idoc/"> - IDoc</ulink></para> - </listitem> - <listitem> - <para><ulink - url="http://www.fmi.uni-passau.de/~groessli/hdoc/">HDoc</ulink></para> - </listitem> - <listitem> - <para><ulink url="http://www.stack.nl/~dimitri/doxygen/"> - Doxygen</ulink></para> - </listitem> - </itemizedlist> - - <para>and probably several others I've forgotten.</para> - - <para>Thanks to the the members - of <email>haskelldoc@haskell.org</email>, - <email>haddock@projects.haskell.org</email> and everyone who - contributed to the many libraries that Haddock makes use - of.</para> - </section> - - </chapter> - - <chapter id="invoking"> - <title>Invoking Haddock</title> - <para>Haddock is invoked from the command line, like so:</para> - - <cmdsynopsis> - <command>haddock</command> - <arg rep="repeat"><replaceable>option</replaceable></arg> - <arg rep="repeat" choice="plain"><replaceable>file</replaceable></arg> - </cmdsynopsis> - - <para>Where each <replaceable>file</replaceable> is a filename - containing a Haskell source module (.hs) or a Literate Haskell source - module (.lhs) or just a module name.</para> - - <para>All the modules specified on the command line will be - processed together. When one module refers to an entity in - another module being processed, the documentation will link - directly to that entity.</para> - - <para>Entities that cannot be found, for example because they are - in a module that isn't being processed as part of the current - batch, simply won't be hyperlinked in the generated - documentation. Haddock will emit warnings listing all the - identifiers it couldn't resolve.</para> - - <para>The modules should <emphasis>not</emphasis> be mutually - recursive, as Haddock don't like swimming in circles.</para> - - <para>Note that while older version would fail on invalid markup, this is considered a bug in the - new versions. If you ever get failed parsing message, please report it.</para> - - <para>You must also specify an option for the output format. - Currently only the <option>-h</option> option for HTML and the - <option>--hoogle</option> option for outputting Hoogle data are - functional.</para> - - <para>The packaging - tool <ulink url="http://www.haskell.org/ghc/docs/latest/html/Cabal/index.html">Cabal</ulink> - has Haddock support, and is often used instead of invoking Haddock - directly.</para> - - <para>The following options are available:</para> - - <variablelist> - - <varlistentry> - <term> - <indexterm><primary><option>-B</option></primary></indexterm> - <option>-B</option> <replaceable>dir</replaceable> - </term> - <listitem> - <para>Tell GHC that that its lib directory is - <replaceable>dir</replaceable>. Can be used to override the default path.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-o</option></primary></indexterm> - <option>-o</option> <replaceable>dir</replaceable> - </term> - <term> - <indexterm><primary><option>--odir</option></primary></indexterm> - <option>--odir</option>=<replaceable>dir</replaceable> - </term> - <listitem> - <para>Generate files into <replaceable>dir</replaceable> - instead of the current directory.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-l</option></primary></indexterm> - <option>-l</option> <replaceable>dir</replaceable> - </term> - <term> - <indexterm><primary><option>--lib</option></primary></indexterm> - <option>--lib</option>=<replaceable>dir</replaceable> - </term> - <listitem> - <para>Use Haddock auxiliary files (themes, javascript, etc...) in <replaceable>dir</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-i</option></primary></indexterm> - <option>-i</option> <replaceable>file</replaceable> - </term> - <term> - <indexterm><primary><option>-i</option></primary></indexterm> - <option>-i</option> <replaceable>docpath</replaceable>,<replaceable>file</replaceable> - </term> - <term> - <indexterm><primary><option>-i</option></primary></indexterm> - <option>-i</option> <replaceable>docpath</replaceable>,<replaceable>srcpath</replaceable>,<replaceable>file</replaceable> - </term> - <term> - <indexterm><primary><option>--read-interface</option></primary></indexterm> - <option>--read-interface</option>=<replaceable>file</replaceable> - </term> - <term> - <indexterm><primary><option>--read-interface</option></primary></indexterm> - <option>--read-interface</option>=<replaceable>docpath</replaceable>,<replaceable>file</replaceable> - </term> - <term> - <indexterm><primary><option>--read-interface</option></primary></indexterm> - <option>--read-interface</option>=<replaceable>docpath</replaceable>,<replaceable>srcpath</replaceable>,<replaceable>file</replaceable> - </term> - <listitem> - <para>Read the interface file in - <replaceable>file</replaceable>, which must have been - produced by running Haddock with the - <option>--dump-interface</option> option. The interface - describes a set of modules whose HTML documentation is - located in <replaceable>docpath</replaceable> (which may be a - relative pathname). The <replaceable>docpath</replaceable> is - optional, and defaults to <quote>.</quote>. The - <replaceable>srcpath</replaceable> is optional but has no default - value.</para> - - <para>This option allows Haddock to produce separate sets of - documentation with hyperlinks between them. The - <replaceable>docpath</replaceable> is used to direct hyperlinks - to point to the right files; so make sure you don't move the - HTML files later or these links will break. Using a - relative <replaceable>docpath</replaceable> means that a - documentation subtree can still be moved around without - breaking links.</para> - - <para>Similarly to <replaceable>docpath</replaceable>, <replaceable>srcpath</replaceable> is used generate cross-package hyperlinks but - within sources rendered with <option>--hyperlinked-source</option> - option.</para> - - <para>Multiple <option>--read-interface</option> options may - be given.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-D</option></primary></indexterm> - <option>-D</option> <replaceable>file</replaceable> - </term> - <term> - <indexterm><primary><option>--dump-interface</option></primary></indexterm> - <option>--dump-interface</option>=<replaceable>file</replaceable> - </term> - <listitem> - <para>Produce an <firstterm>interface - file</firstterm><footnote><para>Haddock interface files are - not the same as Haskell interface files, I just couldn't - think of a better name.</para> </footnote> - in the file <replaceable>file</replaceable>. An interface - file contains information Haddock needs to produce more - documentation that refers to the modules currently being - processed - see the <option>--read-interface</option> option - for more details. The interface file is in a binary format; - don't try to read it.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-h</option></primary></indexterm> - <option>-h</option> - </term> - <term> - <indexterm><primary><option>--html</option></primary></indexterm> - <option>--html</option> - </term> - <listitem> - <para>Generate documentation in HTML format. Several files - will be generated into the current directory (or the - specified directory if the <option>-o</option> option is - given), including the following:</para> - <variablelist> - <varlistentry> - <term><filename><replaceable>module</replaceable>.html</filename></term> - <term><filename>mini_<replaceable>module</replaceable>.html</filename></term> - <listitem> - <para>An HTML page for each - <replaceable>module</replaceable>, and a "mini" page for - each used when viewing in frames.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>index.html</filename></term> - <listitem> - <para>The top level page of the documentation: lists - the modules available, using indentation to represent - the hierarchy if the modules are hierarchical.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>doc-index.html</filename></term> - <term><filename>doc-index-<replaceable>X</replaceable>.html</filename></term> - <listitem> - <para>The alphabetic index, possibly split into multiple - pages if big enough.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>frames.html</filename></term> - <listitem> - <para>The top level document when viewing in frames.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename><replaceable>some</replaceable>.css</filename></term> - <term><filename><replaceable>etc...</replaceable></filename></term> - <listitem> - <para>Files needed for the themes used. Specify your themes - using the <option>--theme</option> option.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>haddock-util.js</filename></term> - <listitem> - <para>Some JavaScript utilities used to implement some of the - dynamic features like collapsible sections, and switching to - frames view.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--latex</option></primary></indexterm> - <option>--latex</option> - </term> - <listitem> - <para>Generate documentation in LaTeX format. Several files - will be generated into the current directory (or the - specified directory if the <option>-o</option> option is - given), including the following:</para> - - <variablelist> - <varlistentry> - <term><filename><replaceable>package</replaceable>.tex</filename></term> - <listitem> - <para>The top-level LaTeX source file; to format the - documentation into PDF you might run something like - this:</para> -<screen> -$ pdflatex <replaceable>package</replaceable>.tex</screen> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>haddock.sty</filename></term> - <listitem> - <para>The default style. The file contains - definitions for various macros used in the LaTeX - sources generated by Haddock; to change the way the - formatted output looks, you might want to override - these by specifying your own style with - the <option>--latex-style</option> option.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename><replaceable>module</replaceable>.tex</filename></term> - <listitem> - <para>The LaTeX documentation for - each <replaceable>module</replaceable>.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--latex-style</option></primary></indexterm> - <option>--latex-style=<replaceable>style</replaceable></option> - </term> - <listitem> - <para>This option lets you override the default style used - by the LaTeX generated by the <option>--latex</option> option. - Normally Haddock puts a - standard <filename>haddock.sty</filename> in the output - directory, and includes the - command <literal>\usepackage{haddock}</literal> in the - LaTeX source. If this option is given, - then <filename>haddock.sty</filename> is not generated, - and the command is - instead <literal>\usepackage{<replaceable>style</replaceable>}</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--hyperlinked-source</option></primary></indexterm> - <option>--hyperlinked-source</option> - </term> - <listitem> - <para>Generate hyperlinked source code (as HTML web page). All - rendered files will be put into - <filename class='directory'>src/</filename> subfolder of output - directory.</para> - <para>Usually, this should be used in combination with - <option>--html</option> option - generated documentation will then - contain references to appropriate code fragments. Previously, this - behaviour could be achieved by generating sources using external - tool and specifying <option>--source-base</option>, - <option>--source-module</option>, <option>--source-entity</option> - and related options. Note that these flags are ignored once - <option>--hyperlinked-source</option> is set.</para> - <para>In order to make cross-package source hyperlinking possible, - appropriate source paths have to be set up when providing - interface files using <option>--read-interface</option> - option.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--source-css</option></primary></indexterm> - <option>--source-css=<replaceable>style</replaceable></option> - </term> - <listitem> - <para>Use custom CSS file for sources rendered by the - <option>--hyperlinked-source</option> option. If no custom style - file is provided, Haddock will use default one.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-S</option></primary></indexterm> - <option>-S</option> - </term> - <term> - <indexterm><primary><option>--docbook</option></primary></indexterm> - <option>--docbook</option> - </term> - <listitem> - <para>Reserved for future use (output documentation in DocBook XML - format).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--source-base</option></primary></indexterm> - <option>--source-base</option>=<replaceable>URL</replaceable> - </term> - <term> - <indexterm><primary><option>--source-module</option></primary></indexterm> - <option>--source-module</option>=<replaceable>URL</replaceable> - </term> - <term> - <indexterm><primary><option>--source-entity</option></primary></indexterm> - <option>--source-entity</option>=<replaceable>URL</replaceable> - </term> - <term> - <indexterm><primary><option>--source-entity-line</option></primary></indexterm> - <option>--source-entity-line</option>=<replaceable>URL</replaceable> - </term> - <listitem> - <para>Include links to the source files in the generated - documentation. Use the <option>--source-base</option> option to add a - source code link in the header bar of the contents and index pages. - Use the <option>--source-module</option> to add a source code link in - the header bar of each module page. Use the - <option>--source-entity</option> option to add a source code link - next to the documentation for every value and type in each module. - <option>--source-entity-line</option> is a flag that gets used for - entities that need to link to an exact source location rather than a - name, eg. since they were defined inside a Template Haskell splice. - </para> - - <para>In each case <replaceable>URL</replaceable> is the base URL - where the source files can be found. For the per-module and - per-entity URLs, the following substitutions are made within the - string <replaceable>URL</replaceable>:</para> - - <itemizedlist> - <listitem> - <para>The string <literal>%M</literal> or <literal>%{MODULE}</literal> - is replaced by the module name. Note that for the per-entity URLs - this is the name of the <emphasis>exporting</emphasis> module.</para> - </listitem> - <listitem> - <para>The string <literal>%F</literal> or <literal>%{FILE}</literal> - is replaced by the original source file name. Note that for the - per-entity URLs this is the name of the <emphasis>defining</emphasis> - module.</para> - </listitem> - <listitem> - <para>The string <literal>%N</literal> or <literal>%{NAME}</literal> - is replaced by the name of the exported value or type. This is - only valid for the <option>--source-entity</option> option.</para> - </listitem> - <listitem> - <para>The string <literal>%K</literal> or <literal>%{KIND}</literal> - is replaced by a flag indicating whether the exported name is a value - '<literal>v</literal>' or a type '<literal>t</literal>'. This is - only valid for the <option>--source-entity</option> option.</para> - </listitem> - <listitem> - <para>The string <literal>%L</literal> or <literal>%{LINE}</literal> - is replaced by the number of the line where the exported value or - type is defined. This is only valid for the - <option>--source-entity</option> option.</para> - </listitem> - <listitem> - <para>The string <literal>%%</literal> is replaced by - <literal>%</literal>.</para> - </listitem> - - </itemizedlist> - - <para>For example, if your sources are online under some directory, - you would say - <literal>haddock --source-base=<replaceable>url</replaceable>/ - --source-module=<replaceable>url</replaceable>/%F</literal></para> - - <para>If you have html versions of your sources online with anchors - for each type and function name, you would say - <literal>haddock --source-base=<replaceable>url</replaceable>/ - --source-module=<replaceable>url</replaceable>/%M.html - --source-entity=<replaceable>url</replaceable>/%M.html#%N</literal></para> - - <para>For the <literal>%{MODULE}</literal> substitution you may want to - replace the '<literal>.</literal>' character in the module names with - some other character (some web servers are known to get confused by - multiple '<literal>.</literal>' characters in a file name). To - replace it with a character <replaceable>c</replaceable> use - <literal>%{MODULE/./<replaceable>c</replaceable>}</literal>.</para> - - <para>Similarly, for the <literal>%{FILE}</literal> substitution - you may want to replace the '<literal>/</literal>' character in - the file names with some other character (especially for links - to colourised entity source code with a shared css file). To replace - it with a character <replaceable>c</replaceable> use - <literal>%{FILE///<replaceable>c</replaceable>}</literal>/</para> - - <para>One example of a tool that can generate syntax-highlighted - HTML from your source code, complete with anchors suitable for use - from haddock, is - <ulink url="http://www.cs.york.ac.uk/fp/darcs/hscolour">hscolour</ulink>.</para> - - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-s</option></primary></indexterm> - <option>-s</option> <replaceable>URL</replaceable> - </term> - <term> - <indexterm><primary><option>--source</option></primary></indexterm> - <option>--source</option>=<replaceable>URL</replaceable> - </term> - <listitem> - <para>Deprecated aliases for <option>--source-module</option></para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--comments-base</option></primary></indexterm> - <option>--comments-base</option>=<replaceable>URL</replaceable> - </term> - <term> - <indexterm><primary><option>--comments-module</option></primary></indexterm> - <option>--comments-module</option>=<replaceable>URL</replaceable> - </term> - <term> - <indexterm><primary><option>--comments-entity</option></primary></indexterm> - <option>--comments-entity</option>=<replaceable>URL</replaceable> - </term> - <listitem> - <para>Include links to pages where readers may comment on the - documentation. This feature would typically be used in conjunction - with a Wiki system.</para> - - <para>Use the <option>--comments-base</option> option to add a - user comments link in the header bar of the contents and index pages. - Use the <option>--comments-module</option> to add a user comments - link in the header bar of each module page. Use the - <option>--comments-entity</option> option to add a comments link - next to the documentation for every value and type in each module. - </para> - - <para>In each case <replaceable>URL</replaceable> is the base URL - where the corresponding comments page can be found. For the - per-module and per-entity URLs the same substitutions are made as - with the <option>--source-module</option> and - <option>--source-entity</option> options above.</para> - - <para>For example, if you want to link the contents page to a wiki - page, and every module to subpages, you would say - <literal>haddock --comments-base=<replaceable>url</replaceable> - --comments-module=<replaceable>url</replaceable>/%M</literal></para> - - <para>If your Wiki system doesn't like the '<literal>.</literal>' character - in Haskell module names, you can replace it with a different character. For - example to replace the '<literal>.</literal>' characters with - '<literal>_</literal>' use <literal>haddock - --comments-base=<replaceable>url</replaceable> - --comments-module=<replaceable>url</replaceable>/%{MODULE/./_}</literal> - Similarly, you can replace the '<literal>/</literal>' in a file name (may - be useful for entity comments, but probably not.) </para> - - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--theme</option></primary></indexterm> - <option>--theme</option>=<replaceable>path</replaceable> - </term> - <listitem> - <para>Specify a theme to be used for HTML (<option>--html</option>) - documentation. If given multiple times then the pages will use the - first theme given by default, and have alternate style sheets for - the others. The reader can switch between themes with browsers that - support alternate style sheets, or with the "Style" menu that gets - added when the page is loaded. If - no themes are specified, then just the default built-in theme - ("Ocean") is used. - </para> - - <para>The <replaceable>path</replaceable> parameter can be one of: - </para> - - <itemizedlist> - <listitem> - <para>A <emphasis>directory</emphasis>: The base name of - the directory becomes the name of the theme. The directory - must contain exactly one - <filename><replaceable>some</replaceable>.css</filename> file. - Other files, usually image files, will be copied, along with - the <filename><replaceable>some</replaceable>.css</filename> - file, into the generated output directory.</para> - </listitem> - <listitem> - <para>A <emphasis>CSS file</emphasis>: The base name of - the file becomes the name of the theme.</para> - </listitem> - <listitem> - <para>The <emphasis>name</emphasis> of a built-in theme - ("Ocean" or "Classic").</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--built-in-themes</option></primary></indexterm> - <option>--built-in-themes</option> - </term> - <listitem> - <para>Includes the built-in themes ("Ocean" and "Classic"). - Can be combined with <option>--theme</option>. Note that order - matters: The first specified theme will be the default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-c</option></primary></indexterm> - <option>-c</option> <replaceable>file</replaceable> - </term> - <term> - <indexterm><primary><option>--css</option></primary></indexterm> - <option>--css</option>=<replaceable>file</replaceable> - </term> - <listitem> - <para>Deprecated aliases for <option>--theme</option></para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-p</option></primary></indexterm> - <option>-p</option> <replaceable>file</replaceable> - </term> - <term> - <indexterm><primary><option>--prologue</option></primary></indexterm> - <option>--prologue</option>=<replaceable>file</replaceable> - </term> - <listitem> - <para>Specify a file containing documentation which is - placed on the main contents page under the heading - “Description”. The file is parsed as a normal - Haddock doc comment (but the comment markers are not - required).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-t</option></primary></indexterm> - <option>-t</option> <replaceable>title</replaceable> - </term> - <term> - <indexterm><primary><option>--title</option></primary></indexterm> - <option>--title</option>=<replaceable>title</replaceable> - </term> - <listitem> - <para>Use <replaceable>title</replaceable> as the page - heading for each page in the documentation.This will - normally be the name of the library being documented.</para> - - <para>The title should be a plain string (no markup - please!).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-q</option></primary></indexterm> - <option>-q</option> <replaceable>mode</replaceable> - </term> - <term> - <indexterm><primary><option>--qual</option></primary></indexterm> - <option>--qual</option>=<replaceable>mode</replaceable> - </term> - <listitem> - <para> - Specify how identifiers are qualified. - </para> - <para> - <replaceable>mode</replaceable> should be one of - <itemizedlist> - <listitem> - <para>none (default): don't qualify any identifiers</para> - </listitem> - <listitem> - <para>full: always qualify identifiers completely</para> - </listitem> - <listitem> - <para>local: only qualify identifiers that are not part - of the module</para> - </listitem> - <listitem> - <para>relative: like local, but strip name of the module - from qualifications of identifiers in submodules</para> - </listitem> - </itemizedlist> - </para> - <para> - Example: If you generate documentation for module A, then the - identifiers A.x, A.B.y and C.z are qualified as follows. - </para> - <para> - <itemizedlist> - <listitem> - <simpara>none: x, y, z</simpara> - </listitem> - <listitem> - <simpara>full: A.x, A.B.y, C.z</simpara> - </listitem> - <listitem> - <simpara>local: x, A.B.y, C.z</simpara> - </listitem> - <listitem> - <simpara>relative: x, B.y, C.z</simpara> - </listitem> - </itemizedlist> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-?</option></primary></indexterm> - <option>-?</option> - </term> - <term> - <indexterm><primary><option>--help</option></primary></indexterm> - <option>--help</option> - </term> - <listitem> - <para>Display help and exit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-V</option></primary></indexterm> - <option>-V</option> - </term> - <term> - <indexterm><primary><option>--version</option></primary></indexterm> - <option>--version</option> - </term> - <listitem> - <para>Output version information and exit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-v</option></primary></indexterm> - <option>-v</option> - </term> - <term> - <indexterm><primary><option>--verbose</option></primary></indexterm> - <option>--verbose</option> - </term> - <listitem> - <para>Increase verbosity. Currently this will cause Haddock - to emit some extra warnings, in particular about modules - which were imported but it had no information about (this is - often quite normal; for example when there is no information - about the <literal>Prelude</literal>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--use-contents</option></primary></indexterm> - <option>--use-contents=<replaceable>URL</replaceable></option> - </term> - <term> - <indexterm><primary><option>--use-index</option></primary></indexterm> - <option>--use-index=<replaceable>URL</replaceable></option> - </term> - <listitem> - <para>When generating HTML, do not generate an index. - Instead, redirect the Contents and/or Index link on each page to - <replaceable>URL</replaceable>. This option is intended for - use in conjunction with <option>--gen-contents</option> and/or - <option>--gen-index</option> for - generating a separate contents and/or index covering multiple - libraries.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--gen-contents</option></primary></indexterm> - <option>--gen-contents</option> - </term> - <term> - <indexterm><primary><option>--gen-index</option></primary></indexterm> - <option>--gen-index</option> - </term> - <listitem> - <para>Generate an HTML contents and/or index containing entries pulled - from all the specified interfaces (interfaces are specified using - <option>-i</option> or <option>--read-interface</option>). - This is used to generate a single contents and/or index for multiple - sets of Haddock documentation.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--ignore-all-exports</option></primary> - </indexterm> - <option>--ignore-all-exports</option> - </term> - <listitem> - <para>Causes Haddock to behave as if every module has the - <literal>ignore-exports</literal> attribute (<xref - linkend="module-attributes" />). This might be useful for - generating implementation documentation rather than interface - documentation, for example.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--hide</option></primary> - </indexterm> - <option>--hide</option> <replaceable>module</replaceable> - </term> - <listitem> - <para>Causes Haddock to behave as if module - <replaceable>module</replaceable> has the <literal>hide</literal> - attribute. (<xref linkend="module-attributes" />).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--show-extensions</option></primary> - </indexterm> - <option>--show-extensions</option> <replaceable>module</replaceable> - </term> - <listitem> - <para>Causes Haddock to behave as if module - <replaceable>module</replaceable> has the <literal>show-extensions</literal> - attribute. (<xref linkend="module-attributes" />).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--optghc</option></primary></indexterm> - <option>--optghc</option>=<replaceable>option</replaceable> - </term> - <listitem> - <para>Pass <replaceable>option</replaceable> to GHC. Note that there is a double dash there, unlike for GHC.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>-w</option></primary></indexterm> - <option>-w</option> - </term> - <term> - <indexterm><primary><option>--no-warnings</option></primary></indexterm> - <option>--no-warnings</option> - </term> - <listitem> - <para>Turn off all warnings.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--compatible-interface-versions</option></primary></indexterm> - <option>--compatible-interface-versions</option> - </term> - <listitem> - <para> - Prints out space-separated versions of binary Haddock interface files that this version is compatible - with. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--no-tmp-comp-dir</option></primary></indexterm> - <option>--no-tmp-comp-dir</option> - </term> - <listitem> - <para> - Do not use a temporary directory for reading and writing compilation output files - (<literal>.o</literal>, <literal>.hi</literal>, and stub files). Instead, use the - present directory or another directory that you have explicitly told GHC to use - via the <literal>--optghc</literal> flag. - </para> - <para> - This flag can be used to avoid recompilation if compilation files already exist. - Compilation files are produced when Haddock has to process modules that make use of - Template Haskell, in which case Haddock compiles the modules using the GHC API. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><option>--print-missing-docs</option></primary></indexterm> - <option>--print-missing-docs</option> - </term> - <listitem> - <para> - Print extra information about any undocumented entities. - </para> - </listitem> - </varlistentry> - </variablelist> - - <section id="cpp"> - <title>Using literate or pre-processed source</title> - - <para>Since Haddock uses GHC internally, both plain and - literate Haskell sources are accepted without the need for the user - to do anything. To use the C pre-processor, however, - the user must pass the the <option>-cpp</option> option to GHC - using <option>--optghc</option>. - </para> - </section> - - </chapter> - - <chapter id="markup"> - <title>Documentation and Markup</title> - - <para>Haddock understands special documentation annotations in the - Haskell source file and propagates these into the generated - documentation. The annotations are purely optional: if there are - no annotations, Haddock will just generate documentation that - contains the type signatures, data type declarations, and class - declarations exported by each of the modules being - processed.</para> - - <section> - <title>Documenting a top-level declaration</title> - - <para>The simplest example of a documentation annotation is for - documenting any top-level declaration (function type signature, - type declaration, or class declaration). For example, if the - source file contains the following type signature:</para> - -<programlisting> -square :: Int -> Int -square x = x * x -</programlisting> - - <para>Then we can document it like this:</para> - -<programlisting> --- |The 'square' function squares an integer. -square :: Int -> Int -square x = x * x -</programlisting> - - - <para>The <quote><literal>-- |</literal></quote> syntax begins a - documentation annotation, which applies to the - <emphasis>following</emphasis> declaration in the source file. - Note that the annotation is just a comment in Haskell — it - will be ignored by the Haskell compiler.</para> - - <para>The declaration following a documentation annotation - should be one of the following:</para> - <itemizedlist> - <listitem> - <para>A type signature for a top-level function,</para> - </listitem> - <listitem> - <para>A <literal>data</literal> declaration,</para> - </listitem> - <listitem> - <para>A <literal>newtype</literal> declaration,</para> - </listitem> - <listitem> - <para>A <literal>type</literal> declaration</para> - </listitem> - <listitem> - <para>A <literal>class</literal> declaration,</para> - </listitem> - <listitem> - <para>A <literal>data family</literal> or - <literal>type family</literal> declaration, or</para> - </listitem> - <listitem> - <para>A <literal>data instance</literal> or - <literal>type instance</literal> declaration.</para> - </listitem> - </itemizedlist> - - <para>If the annotation is followed by a different kind of - declaration, it will probably be ignored by Haddock.</para> - - <para>Some people like to write their documentation - <emphasis>after</emphasis> the declaration; this is possible in - Haddock too:</para> - -<programlisting> -square :: Int -> Int --- ^The 'square' function squares an integer. -square x = x * x -</programlisting> - - <para>Note that Haddock doesn't contain a Haskell type system - — if you don't write the type signature for a function, - then Haddock can't tell what its type is and it won't be - included in the documentation.</para> - - <para>Documentation annotations may span several lines; the - annotation continues until the first non-comment line in the - source file. For example:</para> - -<programlisting> --- |The 'square' function squares an integer. --- It takes one argument, of type 'Int'. -square :: Int -> Int -square x = x * x -</programlisting> - - <para>You can also use Haskell's nested-comment style for - documentation annotations, which is sometimes more convenient - when using multi-line comments:</para> - -<programlisting> -{-| - The 'square' function squares an integer. - It takes one argument, of type 'Int'. --} -square :: Int -> Int -square x = x * x -</programlisting> - - </section> - <section> - <title>Documenting parts of a declaration</title> - - <para>In addition to documenting the whole declaration, in some - cases we can also document individual parts of the - declaration.</para> - - <section> - <title>Class methods</title> - - <para>Class methods are documented in the same way as top - level type signatures, by using either the - <quote><literal>-- |</literal></quote> or - <quote><literal>-- ^</literal></quote> - annotations:</para> - -<programlisting> -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 -</programlisting> - </section> - - <section> - <title>Constructors and record fields</title> - - <para>Constructors are documented like so:</para> - -<programlisting> -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 -</programlisting> - - <para>or like this:</para> - -<programlisting> -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 -</programlisting> - - <para>Record fields are documented using one of these - styles:</para> - -<programlisting> -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 - } -</programlisting> - - <para>Alternative layout styles are generally accepted by - Haddock - for example doc comments can appear before or after - the comma in separated lists such as the list of record fields - above.</para> - - <para>In case that more than one constructor exports a field - with the same name, the documentation attached to the first - occurence of the field will be used, even if a comment is not - present. - </para> - -<programlisting> -data T a = A { someField :: a -- ^ Doc for someField of A - } - | B { someField :: a -- ^ Doc for someField of B - } -</programlisting> - - <para>In the above example, all occurences of - <literal>someField</literal> in the documentation are going to - be documented with <literal>Doc for someField of A</literal>. - Note that Haddock versions 2.14.0 and before would join up - documentation of each field and render the result. The reason - for this seemingly weird behaviour is the fact that - <literal>someField</literal> is actually the same (partial) - function.</para> - - </section> - - <section> - <title>Function arguments</title> - - <para>Individual arguments to a function may be documented - like this:</para> - -<programlisting> -f :: Int -- ^ The 'Int' argument - -> Float -- ^ The 'Float' argument - -> IO () -- ^ The return value -</programlisting> - </section> - </section> - - <section> - <title>The module description</title> - - <para>A module itself may be documented with multiple fields - that can then be displayed by the backend. In particular, the - HTML backend displays all the fields it currently knows - about. We first show the most complete module documentation - example and then talk about the fields.</para> - -<programlisting> -{-| -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 -... -</programlisting> - - <para>The <quote>Module</quote> field should be clear. It - currently doesn't affect the output of any of the backends but - you might want to include it for human information or for any - other tools that might be parsing these comments without the - help of GHC.</para> - - <para>The <quote>Description</quote> field accepts some short text - which outlines the general purpose of the module. If you're - generating HTML, it will show up next to the module link in - the module index.</para> - - <para>The <quote>Copyright</quote>, <quote>License</quote>, - <quote>Maintainer</quote> and <quote>Stability</quote> fields - should be obvious. An alternative spelling for the - <quote>License</quote> field is accepted as - <quote>Licence</quote> but the output will always prefer - <quote>License</quote>.</para> - - <para>The <quote>Portability</quote> field has seen varied use - by different library authors. Some people put down things like - operating system constraints there while others put down which GHC - extensions are used in the module. Note that you might want to - consider using the <quote>show-extensions</quote> module flag for the - latter.</para> - - <para>Finally, a module may contain a documentation comment - before the module header, in which case this comment is - interpreted by Haddock as an overall description of the module - itself, and placed in a section entitled - <quote>Description</quote> in the documentation for the module. - All usual Haddock markup is valid in this comment.</para> - - <para>All fields are optional but they must be in order if they - do appear. Multi-line fields are accepted but the consecutive - lines have to start indented more than their label. If your - label is indented one space as is often the case with - <quote>--</quote> syntax, the consecutive lines have to start at - two spaces at the very least. Please note that we do not enforce - the format for any of the fields and the established formats are - just a convention.</para> - - </section> - - <section> - <title>Controlling the documentation structure</title> - - <para>Haddock produces interface documentation that lists only - the entities actually exported by the module. The documentation - for a module will include <emphasis>all</emphasis> entities - exported by that module, even if they were re-exported by - another module. The only exception is when Haddock can't see - the declaration for the re-exported entity, perhaps because it - isn't part of the batch of modules currently being - processed.</para> - - <para>However, to Haddock the export list has even more - significance than just specifying the entities to be included in - the documentation. It also specifies the - <emphasis>order</emphasis> 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 <emphasis>module</emphasis> 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.</para> - - <para>You can insert headings and sub-headings in the - documentation by including annotations at the appropriate point - in the export list. For example:</para> - -<programlisting> -module Foo ( - -- * Classes - C(..), - -- * Types - -- ** A data type - T, - -- ** A record - R, - -- * Some functions - f, g - ) where -</programlisting> - - <para>Headings are introduced with the syntax - <quote><literal>-- *</literal></quote>, - <quote><literal>-- **</literal></quote> and so on, where - the number of <literal>*</literal>s indicates the level of the - heading (section, sub-section, sub-sub-section, etc.).</para> - - <para>If you use section headings, then Haddock will generate a - table of contents at the top of the module documentation for - you.</para> - - <para>The alternative style of placing the commas at the - beginning of each line is also supported. eg.:</para> - -<programlisting> -module Foo ( - -- * Classes - , C(..) - -- * Types - -- ** A data type - , T - -- ** A record - , R - -- * Some functions - , f - , g - ) where -</programlisting> - - <section> - <title>Re-exporting an entire module</title> - - <para>Haskell allows you to re-export the entire contents of a - module (or at least, everything currently in scope that was - imported from a given module) by listing it in the export - list:</para> - -<programlisting> -module A ( - module B, - module C - ) where -</programlisting> - - <para>What will the Haddock-generated documentation for this - module look like? Well, it depends on how the modules - <literal>B</literal> and <literal>C</literal> are imported. - If they are imported wholly and without any - <literal>hiding</literal> qualifiers, then the documentation - will just contain a cross-reference to the documentation for - <literal>B</literal> and <literal>C</literal>. However, if - the modules are not <emphasis>completely</emphasis> - re-exported, for example:</para> - -<programlisting> -module A ( - module B, - module C - ) where - -import B hiding (f) -import C (a, b) -</programlisting> - - <para>then Haddock behaves as if the set of entities - re-exported from <literal>B</literal> and <literal>C</literal> - had been listed explicitly in the export - list<footnote><para>NOTE: this is not fully implemented at the - time of writing (version 0.2). At the moment, Haddock always - inserts a cross-reference.</para> - </footnote>.</para> - - <para>The exception to this rule is when the re-exported - module is declared with the <literal>hide</literal> attribute - (<xref linkend="module-attributes"/>), in which case the module - is never cross-referenced; the contents are always expanded in - place in the re-exporting module.</para> - </section> - - <section> - <title>Omitting the export list</title> - - <para>If there is no export list in the module, how does - Haddock generate documentation? Well, when the export list is - omitted, e.g.:</para> - -<programlisting>module Foo where</programlisting> - - <para>this is equivalent to an export list which mentions - every entity defined at the top level in this module, and - Haddock treats it in the same way. Furthermore, the generated - documentation will retain the order in which entities are - defined in the module. In this special case the module body - may also include section headings (normally they would be - ignored by Haddock).</para> - -<programlisting> -module Foo where - --- * This heading will now appear before foo. - --- | Documentation for 'foo'. -foo :: Integer -foo = 5 -</programlisting> - - </section> - </section> - - <section> - <title>Named chunks of documentation</title> - - <para>Occasionally it is desirable to include a chunk of - documentation which is not attached to any particular Haskell - declaration. There are two ways to do this:</para> - - <itemizedlist> - <listitem> - <para>The documentation can be included in the export list - directly, e.g.:</para> - -<programlisting> -module Foo ( - -- * A section heading - - -- | Some documentation not attached to a particular Haskell entity - ... - ) where -</programlisting> - </listitem> - - <listitem> - <para>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. This is achieved with a - special form of documentation annotation - <quote><literal>-- $</literal></quote>:</para> - -<programlisting> -module Foo ( - -- * A section heading - - -- $doc - ... - ) where - --- $doc --- Here is a large chunk of documentation which may be referred to by --- the name $doc. -</programlisting> - - <para>The documentation chunk is given a name, which is the - sequence of alphanumeric characters directly after the - <quote><literal>-- $</literal></quote>, and it may be - referred to by the same name in the export list.</para> - </listitem> - </itemizedlist> - </section> - - <section id="hyperlinking"> - <title>Hyperlinking and re-exported entities</title> - - <para>When Haddock renders a type in the generated - documentation, it hyperlinks all the type constructors and class - names in that type to their respective definitions. But for a - given type constructor or class there may be several modules - re-exporting it, and therefore several modules whose - documentation contains the definition of that type or class - (possibly including the current module!) so which one do we link - to?</para> - - <para>Let's look at an example. Suppose we have three modules - <literal>A</literal>, <literal>B</literal> and - <literal>C</literal> defined as follows:</para> - -<programlisting> -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 -</programlisting> - - <para>Module <literal>A</literal> exports a datatype - <literal>T</literal>. Module <literal>B</literal> imports - <literal>A</literal> and exports a function <literal>f</literal> - whose type refers to <literal>T</literal>. Also, both - <literal>T</literal> and <literal>f</literal> are re-exported from - module C.</para> - - <para>Haddock takes the view that each entity has a - <emphasis>home</emphasis> 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.</para> - - <para>How is the home module for an entity determined? - Haddock uses the following rules:</para> - - <itemizedlist> - <listitem> - <para>If modules A and B both export the entity, and module A imports - (directly or indirectly) module B, then B is preferred.</para> - </listitem> - <listitem> - <para>A module with the <literal>hide</literal> attribute is never - chosen as the home.</para> - </listitem> - <listitem> - <para>A module with the <literal>not-home</literal> attribute is only - chosen if there are no other modules to choose.</para> - </listitem> - </itemizedlist> - - <para>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.</para> - - <para>In the example above, module <literal>A</literal> is chosen as the - home for <literal>T</literal> because it does not import any other - module that exports <literal>T</literal>. The link from - <literal>f</literal>'s - type in module <literal>B</literal> will therefore point to - <literal>A.T</literal>. However, <literal>C</literal> also exports - <literal>T</literal> and <literal>f</literal>, and the link from - <literal>f</literal>'s type in <literal>C</literal> will therefore - point locally to <literal>C.T</literal>.</para> - </section> - - <section id="module-attributes"> - <title>Module Attributes</title> - - <para>Certain attributes may be specified for each module which - affects the way that Haddock generates documentation for that - module. Attributes are specified in a comma-separated list in an - <literal>{-# OPTIONS_HADDOCK ... #-}</literal> pragma at the - top of the module, either before or after the module - description. For example:</para> - -<programlisting> -{-# OPTIONS_HADDOCK hide, prune, ignore-exports #-} - --- |Module description -module A where -... -</programlisting> - - <para>The options and module description can be in either order.</para> - - <para>The following attributes are currently understood by - Haddock:</para> - - <variablelist> - <varlistentry> - <term> - <indexterm><primary><literal>hide</literal></primary></indexterm> - <literal>hide</literal> - </term> - <listitem> - <para>Omit this module from the generated documentation, - but nevertheless propagate definitions and documentation - from within this module to modules that re-export those - definitions.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><literal>hide</literal></primary></indexterm> - <literal>prune</literal> - </term> - <listitem> - <para>Omit definitions that have no documentation - annotations from the generated documentation.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><literal>ignore-exports</literal></primary></indexterm> - <literal>ignore-exports</literal> - </term> - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><literal>not-home</literal></primary></indexterm> - <literal>not-home</literal> - </term> - <listitem> - <para>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 - <xref linkend="hyperlinking" /> for more details.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <indexterm><primary><literal>show-extensions</literal></primary></indexterm> - <literal>show-extensions</literal> - </term> - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - - </variablelist> - - </section> - - <section> - <title>Markup</title> - - <para>Haddock understands certain textual cues inside - documentation annotations that tell it how to render the - documentation. The cues (or <quote>markup</quote>) have been - designed to be simple and mnemonic in ASCII so that the - programmer doesn't have to deal with heavyweight annotations - when editing documentation comments.</para> - - <section> - <title>Paragraphs</title> - - <para>One or more blank lines separates two paragraphs in a - documentation comment.</para> - </section> - - <section> - <title>Special characters</title> - - <para>The following characters have special meanings in - documentation comments: <literal>\</literal>, <literal>/</literal>, - <literal>'</literal>, <literal>`</literal>, - <literal>"</literal>, <literal>@</literal>, - <literal><</literal>. To insert a literal occurrence of - one of these special characters, precede it with a backslash - (<literal>\</literal>).</para> - - <para>Additionally, the character <literal>></literal> has - a special meaning at the beginning of a line, and the - following characters have special meanings at the beginning of - a paragraph: - <literal>*</literal>, <literal>-</literal>. These characters - can also be escaped using <literal>\</literal>.</para> - - <para>Furthermore, the character sequence <literal>>>></literal> - has a special meaning at the beginning of a line. To - escape it, just prefix the characters in the sequence with a - backslash.</para> - </section> - - <section> - <title>Character references</title> - - <para>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 - <literal>&#</literal><replaceable>D</replaceable><literal>;</literal> - and - <literal>&#x</literal><replaceable>H</replaceable><literal>;</literal> - where <replaceable>D</replaceable> and <replaceable>H</replaceable> - are decimal and hexadecimal numbers denoting a code position - in Unicode (or ISO 10646). For example, the references - <literal>&#x3BB;</literal>, <literal>&#x3bb;</literal> - and <literal>&#955;</literal> all represent the lower-case - letter lambda.</para> - </section> - - <section> - <title>Code Blocks</title> - - <para>Displayed blocks of code are indicated by surrounding a - paragraph with <literal>@...@</literal> or by preceding each - line of a paragraph with <literal>></literal> (we often - call these “bird tracks”). For - example:</para> - -<programlisting> --- | This documentation includes two blocks of code: --- --- @ --- f x = x + x --- @ --- --- > g x = x * 42 -</programlisting> - - <para>There is an important difference between the two forms - of code block: in the bird-track form, the text to the right - of the ‘<literal>></literal>’ is interpreted - literally, whereas the <literal>@...@</literal> form - interprets markup as normal inside the code block.</para> - </section> - - <section> - <title>Examples</title> - - <para> Haddock has markup support for examples of interaction with a - <emphasis>read-eval-print loop (REPL)</emphasis>. An - example is introduced with - <literal>>>></literal> followed by an expression followed - by zero or more result lines:</para> - -<programlisting> --- | Two examples are given below: --- --- >>> fib 10 --- 55 --- --- >>> putStrLn "foo\nbar" --- foo --- bar -</programlisting> - <para>Result lines that only contain the string - <literal><BLANKLINE></literal> are rendered as blank lines in the - generated documentation.</para> - </section> - - <section> - <title>Properties</title> - <para> - Haddock provides markup for properties: -<programlisting> --- | Addition is commutative: --- --- prop> a + b = b + a -</programlisting> - This allows third-party applications to extract and verify them. - </para> - </section> - - <section> - <title>Hyperlinked Identifiers</title> - - <para>Referring to a Haskell identifier, whether it be a type, - class, constructor, or function, is done by surrounding it - with single quotes:</para> - -<programlisting> --- | This module defines the type 'T'. -</programlisting> - - <para>If there is an entity <literal>T</literal> in scope in - the current module, then the documentation will hyperlink the - reference in the text to the definition of - <literal>T</literal> (if the output format supports - hyperlinking, of course; in a printed format it might instead - insert a page reference to the definition).</para> - - <para>It is also possible to refer to entities that are not in - scope in the current module, by giving the full qualified name - of the entity:</para> - -<programlisting> --- | The identifier 'M.T' is not in scope -</programlisting> - - <para>If <literal>M.T</literal> is not otherwise in scope, - then Haddock will simply emit a link pointing to the entity - <literal>T</literal> exported from module <literal>M</literal> - (without checking to see whether either <literal>M</literal> - or <literal>M.T</literal> exist).</para> - - <para>To make life easier for documentation writers, a quoted - identifier is only interpreted as such if the quotes surround - a lexically valid Haskell identifier. This means, for - example, that it normally isn't necessary to escape the single - quote when used as an apostrophe:</para> - -<programlisting> --- | I don't have to escape my apostrophes; great, isn't it? -</programlisting> - - <para>Nothing special is needed to hyperlink identifiers which - contain apostrophes themselves: to hyperlink - <literal>foo'</literal> one would simply type - <literal>'foo''</literal>. To hyperlink identifiers written in - infix form, simply put them in quotes as always: - <literal>'`elem`'</literal>.</para> - - <para>For compatibility with other systems, the following - alternative form of markup is accepted<footnote><para> - We chose not to use this as the primary markup for - identifiers because strictly speaking the <literal>`</literal> - character should not be used as a left quote, it is a grave accent.</para> - </footnote>: <literal>`T'</literal>.</para> - </section> - - <section> - <title>Emphasis, Bold and Monospaced text</title> - - <para>Emphasis may be added by surrounding text with - <literal>/.../</literal>. Other markup is valid inside emphasis. To have a forward - slash inside of emphasis, just escape it: <literal>/fo\/o/</literal></para> - - <para>Bold (strong) text is indicated by surrounding it with <literal>__...__</literal>. - Other markup is valid inside bold. For example, <literal>__/foo/__</literal> will make the emphasised - text <literal>foo</literal> bold. You don't have to escape a single underscore if you need it bold: - <literal>__This_text_with_underscores_is_bold__</literal>. - </para> - - <para>Monospaced (or typewriter) text is indicated by - surrounding it with <literal>@...@</literal>. Other markup is - valid inside a monospaced span: for example - <literal>@'f' a b@</literal> will hyperlink the - identifier <literal>f</literal> inside the code fragment.</para> - </section> - - <section> - <title>Linking to modules</title> - - <para>Linking to a module is done by surrounding the module - name with double quotes:</para> - -<programlisting> --- | This is a reference to the "Foo" module. -</programlisting> - - <para>A basic check is done on the syntax of the header name to ensure that it is valid - before turning it into a link but unlike with identifiers, whether the module is in scope isn't checked - and will always be turned into a link. - </para> - - </section> - - <section> - <title>Itemized and Enumerated lists</title> - - <para>A bulleted item is represented by preceding a paragraph - with either <quote><literal>*</literal></quote> or - <quote><literal>-</literal></quote>. A sequence of bulleted - paragraphs is rendered as an itemized list in the generated - documentation, eg.:</para> - -<programlisting> --- | This is a bulleted list: --- --- * first item --- --- * second item -</programlisting> - - <para>An enumerated list is similar, except each paragraph - must be preceded by either - <quote><literal>(<replaceable>n</replaceable>)</literal></quote> - or - <quote><literal><replaceable>n</replaceable>.</literal></quote> - where <replaceable>n</replaceable> is any integer. e.g.</para> - -<programlisting> --- | This is an enumerated list: --- --- (1) first item --- --- 2. second item -</programlisting> - - <para>Lists of the same type don't have to be separated by a newline:</para> -<programlisting> --- | This is an enumerated list: --- --- (1) first item --- 2. second item --- --- This is a bulleted list: --- --- * first item --- * second item -</programlisting> - - <para>You can have more than one line of content in a list element: - </para> -<programlisting> --- | --- * first item --- and more content for the first item --- * second item --- and more content for the second item -</programlisting> - - <para>You can even nest whole paragraphs inside of list elements. The rules - are 4 spaces for each indentation level. You're required to use a newline before - such nested paragraph: - </para> -<programlisting> -{-| -* 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. --} -</programlisting> - <para>The indentation of the first list item is honoured. That is, - in the following example the items are on the same level. Before - Haddock 2.16.1, the second item would have been nested under the - first item which was unexpected. - </para> -<programlisting> -{-| - * foo - - * bar --} -</programlisting> - </section> - - <section> - <title>Definition lists</title> - - <para>Definition lists are written as follows:</para> - -<programlisting> --- | This is a definition list: --- --- [@foo@]: The description of @foo@. --- --- [@bar@]: The description of @bar@. -</programlisting> - - <para>To produce output something like this:</para> - - <variablelist> - <varlistentry> - <term><literal>foo</literal></term> - <listitem> - <para>The description of <literal>foo</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>bar</literal></term> - <listitem> - <para>The description of <literal>bar</literal>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Each paragraph should be preceded by the - “definition term” enclosed in square brackets and followed by a colon. - Other markup operators may be used freely within the - definition term. You can escape <literal>]</literal> with a backslash as usual.</para> - - <para>Same rules about nesting and no newline separation as for bulleted and numbered lists apply. - </para> - - </section> - - <section> - <title>URLs</title> - - <para> - A URL can be included in a documentation comment by surrounding it in - angle brackets, for example: - </para> - -<programlisting> -<http://example.com> -</programlisting> - - <para> - If the output format supports it, the URL will be turned into a - hyperlink when rendered. - </para> - - <para>If Haddock sees something that looks like a URL (such as something starting with - <literal>http://</literal> or <literal>ssh://</literal>) where the URL markup is valid, - it will automatically make it a hyperlink.</para> - </section> - - <section> - <title>Links</title> - - <para> - Haddock supports Markdown syntax for inline links. A link consists - of a link text and a URL. The link text is enclosed in square - brackets and followed by the URL enclosed in regular parentheses, for - example: - </para> - -<programlisting> -[some link](http://example.com) -</programlisting> - <para> - The link text is used as a descriptive text for the URL, if the - output format supports it. - </para> - </section> - - <section> - <title>Images</title> - <para> - Haddock supports Markdown syntax for inline images. This resembles - the syntax for links, but starts with an exclamation mark. An - example looks like this: - </para> - -<programlisting> - -</programlisting> - <para> - If the output format supports it, the image will be rendered inside - the documentation. The image description is used as relpacement text - and/or image title. - </para> - </section> - - <section> - <title>Anchors</title> - - <para>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 <emphasis>anchors</emphasis> to be - included in a documentation comment. The syntax is - <literal>#<replaceable>label</replaceable>#</literal>, where - <replaceable>label</replaceable> is the name of the anchor. - An anchor is invisible in the generated documentation.</para> - - <para>To link to an anchor from elsewhere, use the syntax - <literal>"<replaceable>module</replaceable>#<replaceable>label</replaceable>"</literal> - where <replaceable>module</replaceable> is the module name - containing the anchor, and <replaceable>label</replaceable> 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 - <literal>"<replaceable>module</replaceable>\#<replaceable>label</replaceable>"</literal>. - It is considered deprecated and will be removed in the future.</para> - </section> - - <section> - <title>Headings</title> - <para>Headings inside of comment documentation are possible be preceding them with - a number of <literal>=</literal>s. From 1 to 6 are accepted. Extra <literal>=</literal>s will - be treated as belonging to the text of the heading. Note that it's up to the output format to decide - how to render the different levels. - </para> - -<programlisting> --- | --- = Heading level 1 with some /emphasis/ --- Something underneath the heading. --- --- == /Subheading/ --- More content. --- --- === Subsubheading --- Even more content. -</programlisting> - - <para>Note that while headings have to start on a new paragraph, we allow paragraph-level content to - follow these immediately. - </para> - -<programlisting> --- | --- = Heading level 1 with some __bold__ --- Something underneath the heading. --- --- == /Subheading/ --- More content. --- --- === Subsubheading --- >>> examples are only allowed at the start of paragraphs -</programlisting> - - <para>As of 2.15.1, there's experimental (read: subject to - change or get removed) support for collapsible headers: simply - wrap your existing header title in underscores, as per bold - syntax. The collapsible section will stretch until the end of - the comment or until a header of equal or smaller number of - <literal>=</literal>s.</para> - -<programlisting> --- | --- === __Examples:__ --- >>> Some very long list of examples --- --- ==== This still falls under the collapse --- Some specialised examples --- --- === This is does not go into the collapsable section. --- More content. -</programlisting> - - </section> - - <section> - <title>Metadata</title> - <para>Since Haddock 2.16.0, some support for embedding - metadata in the comments has started to appear. The use of - such data aims to standardise various community conventions in - how such information is conveyed and to provide uniform - rendering. - </para> - - <section> - <title>Since</title> - <para><literal>@since</literal> annotation can be used to - convey information about when the function was introduced or - when it has changed in the way significant to the user. - <literal>@since</literal> is a paragraph-level element. - While multiple such annotations are not an error, only the - one to appear in the comment last will be used. - <literal>@since</literal> has to be followed with a version - number, no further description is currently allowed. The - meaning of this feature is subject to change in the future - per user feedback. - </para> - -<programlisting> --- | --- Some comment --- --- @since 1.2.3 -</programlisting> - - </section> - - </section> - - </section> - </chapter> - <index/> -</book> |