diff options
| -rw-r--r-- | doc/.gitignore | 1 | ||||
| -rw-r--r-- | doc/Makefile | 10 | ||||
| -rw-r--r-- | doc/README.md | 23 | ||||
| -rw-r--r-- | doc/aclocal.m4 | 174 | ||||
| -rw-r--r-- | doc/conf.py | 69 | ||||
| -rw-r--r-- | doc/config.mk.in | 15 | ||||
| -rw-r--r-- | doc/configure.ac | 12 | ||||
| -rw-r--r-- | doc/docbook-xml.mk | 130 | ||||
| -rw-r--r-- | doc/fptools.css | 36 | ||||
| -rw-r--r-- | doc/ghc.mk | 9 | ||||
| -rw-r--r-- | doc/haddock.xml | 2329 | ||||
| -rw-r--r-- | doc/index.rst | 21 | ||||
| -rw-r--r-- | doc/intro.rst | 164 | ||||
| -rw-r--r-- | doc/invoking.rst | 458 | ||||
| -rw-r--r-- | doc/markup.rst | 887 |
15 files changed, 1617 insertions, 2721 deletions
diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 00000000..1bf230d1 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +.build-html
\ No newline at end of file diff --git a/doc/Makefile b/doc/Makefile index 5f88b708..f4356f43 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,6 +1,8 @@ -include config.mk +SPHINX_BUILD ?= sphinx-build -XML_DOC = haddock -INSTALL_XML_DOC = haddock +all : html -include docbook-xml.mk +.PHONY : html + +html : + $(SPHINX_BUILD) -b html . .build-html diff --git a/doc/README.md b/doc/README.md index cf1fc31b..947d7f93 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,25 +1,10 @@ # Haddock documentation -The documentation is in DocBook XML format. You need some tools to -process it: at least xsltproc, and the DocBook XML DTD and XSL -stylesheets. There's a configure script to detect the right way to -process the documentation on your system, and a Makefile to actually -do the processing (so, on Windows, you'll need Cygwin or MSys in -addition to the DocBook XML tools). To build the HTML documentation: +The documentation is in ReStructuredText format. You need +[Sphinx](http://www.sphinx-doc.org/) to process it. To build the HTML +documentation, - $ autoconf - $ ./configure $ make html -which leaves the HTML documentation in a haddock/ subdirectory. +which leaves the HTML documentation the `.build-html/` subdirectory. -Printable documentation can also be produced, eg.: - - $ make pdf - -or - - $ make ps - -Generating the printed formats requires more tools (fop or xmltex) and -tends to be a bit harder. diff --git a/doc/aclocal.m4 b/doc/aclocal.m4 deleted file mode 100644 index 97ffcb76..00000000 --- a/doc/aclocal.m4 +++ /dev/null @@ -1,174 +0,0 @@ -# FP_GEN_DOCBOOK_XML -# ------------------ -# Generates a DocBook XML V4.2 document in conftest.xml. -AC_DEFUN([FP_GEN_DOCBOOK_XML], -[rm -f conftest.xml -cat > conftest.xml << EOF -<?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"> -<book id="test"> - <title>A DocBook Test Document</title> - <chapter id="id-one"> - <title>A Chapter Title</title> - <para>This is a paragraph, referencing <xref linkend="id-two"/>.</para> - </chapter> - <chapter id="id-two"> - <title>Another Chapter Title</title> - <para>This is another paragraph, referencing <xref linkend="id-one"/>.</para> - </chapter> -</book> -EOF -]) # FP_GEN_DOCBOOK_XML - - -# FP_PROG_XSLTPROC -# ---------------- -# Sets the output variable XsltprocCmd to the full path of the XSLT processor -# xsltproc. XsltprocCmd is empty if xsltproc could not be found. -AC_DEFUN([FP_PROG_XSLTPROC], -[AC_PATH_PROG([XsltprocCmd], [xsltproc]) -if test -z "$XsltprocCmd"; then - AC_MSG_WARN([cannot find xsltproc in your PATH, you will not be able to build the documentation]) -fi -])# FP_PROG_XSLTPROC - - -# FP_DIR_DOCBOOK_XSL(XSL-DIRS) -# ---------------------------- -# Check which of the directories XSL-DIRS contains DocBook XSL stylesheets. The -# output variable DIR_DOCBOOK_XSL will contain the first usable directory or -# will be empty if none could be found. -AC_DEFUN([FP_DIR_DOCBOOK_XSL], -[AC_REQUIRE([FP_PROG_XSLTPROC])dnl -if test -n "$XsltprocCmd"; then - AC_CACHE_CHECK([for DocBook XSL stylesheet directory], fp_cv_dir_docbook_xsl, - [FP_GEN_DOCBOOK_XML - fp_cv_dir_docbook_xsl=no - for fp_var in $1; do - if $XsltprocCmd ${fp_var}/html/docbook.xsl conftest.xml > /dev/null 2>&1; then - fp_cv_dir_docbook_xsl=$fp_var - break - fi - done - rm -rf conftest*]) -fi -if test x"$fp_cv_dir_docbook_xsl" = xno; then - AC_MSG_WARN([cannot find DocBook XSL stylesheets, you will not be able to build the documentation]) - DIR_DOCBOOK_XSL= -else - DIR_DOCBOOK_XSL=$fp_cv_dir_docbook_xsl -fi -AC_SUBST([DIR_DOCBOOK_XSL]) -])# FP_DIR_DOCBOOK_XSL - - -# FP_PROG_XMLLINT -# ---------------- -# Sets the output variable XmllintCmd to the full path of the XSLT processor -# xmllint. XmllintCmd is empty if xmllint could not be found. -AC_DEFUN([FP_PROG_XMLLINT], -[AC_PATH_PROG([XmllintCmd], [xmllint]) -if test -z "$XmllintCmd"; then - AC_MSG_WARN([cannot find xmllint in your PATH, you will not be able to validate your documentation]) -fi -])# FP_PROG_XMLLINT - - -# FP_CHECK_DOCBOOK_DTD -# -------------------- -AC_DEFUN([FP_CHECK_DOCBOOK_DTD], -[AC_REQUIRE([FP_PROG_XMLLINT])dnl -if test -n "$XmllintCmd"; then - AC_MSG_CHECKING([for DocBook DTD]) - FP_GEN_DOCBOOK_XML - if $XmllintCmd --valid --noout conftest.xml > /dev/null 2>&1; then - AC_MSG_RESULT([ok]) - else - AC_MSG_RESULT([failed]) - AC_MSG_WARN([cannot find a DTD for DocBook XML V4.2, you will not be able to validate your documentation]) - AC_MSG_WARN([check your XML_CATALOG_FILES environment variable and/or /etc/xml/catalog]) - fi - rm -rf conftest* -fi -])# FP_CHECK_DOCBOOK_DTD - - -# FP_GEN_FO -# ------------------ -# Generates a formatting objects document in conftest.fo. -AC_DEFUN([FP_GEN_FO], -[rm -f conftest.fo -cat > conftest.fo << EOF -<?xml version="1.0"?> -<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"> - <fo:layout-master-set> - <fo:simple-page-master master-name="blank"> - <fo:region-body/> - </fo:simple-page-master> - </fo:layout-master-set> - <fo:page-sequence master-reference="blank"> - <fo:flow flow-name="xsl-region-body"> - <fo:block> - Test! - </fo:block> - </fo:flow> - </fo:page-sequence> -</fo:root> -EOF -]) # FP_GEN_FO - - -# FP_PROG_FOP -# ----------- -# Set the output variable 'FopCmd' to the first working 'fop' in the current -# 'PATH'. Note that /usr/bin/fop is broken in SuSE 9.1 (unpatched), so try -# /usr/share/fop/fop.sh in that case (or no 'fop'), too. -AC_DEFUN([FP_PROG_FOP], -[AC_PATH_PROGS([FopCmd1], [fop]) -if test -n "$FopCmd1"; then - AC_CACHE_CHECK([for $FopCmd1 usability], [fp_cv_fop_usability], - [FP_GEN_FO - if "$FopCmd1" -fo conftest.fo -ps conftest.ps > /dev/null 2>&1; then - fp_cv_fop_usability=yes - else - fp_cv_fop_usability=no - fi - rm -rf conftest*]) - if test x"$fp_cv_fop_usability" = xyes; then - FopCmd=$FopCmd1 - fi -fi -if test -z "$FopCmd"; then - AC_PATH_PROGS([FopCmd2], [fop.sh], , [/usr/share/fop]) - FopCmd=$FopCmd2 -fi -AC_SUBST([FopCmd]) -])# FP_PROG_FOP - - -# FP_PROG_FO_PROCESSOR -# -------------------- -# Try to find an FO processor. PassiveTeX output is sometimes a bit strange, so -# try FOP first. Sets the output variables FopCmd, XmltexCmd, DvipsCmd, and -# PdfxmltexCmd. -AC_DEFUN([FP_PROG_FO_PROCESSOR], -[AC_REQUIRE([FP_PROG_FOP]) -AC_PATH_PROG([XmltexCmd], [xmltex]) -AC_PATH_PROG([DvipsCmd], [dvips]) -if test -z "$FopCmd"; then - if test -z "$XmltexCmd"; then - AC_MSG_WARN([cannot find an FO => DVI converter, you will not be able to build DVI or PostScript documentation]) - else - if test -z "$DvipsCmd"; then - AC_MSG_WARN([cannot find a DVI => PS converter, you will not be able to build PostScript documentation]) - fi - fi - AC_PATH_PROG([PdfxmltexCmd], [pdfxmltex]) - if test -z "$PdfxmltexCmd"; then - AC_MSG_WARN([cannot find an FO => PDF converter, you will not be able to build PDF documentation]) - fi -elif test -z "$XmltexCmd"; then - AC_MSG_WARN([cannot find an FO => DVI converter, you will not be able to build DVI documentation]) -fi -])# FP_PROG_FO_PROCESSOR diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 00000000..d6b8bda8 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,69 @@ +# -*- coding: utf-8 -*- + +import sys +import os +import shlex + +extensions = [] + +source_suffix = '.rst' +master_doc = 'index' + +# General information about the project. +project = u'Haddock' +copyright = u'2016, Simon Marlow' +author = u'Simon Marlow' +version = '1.0' +release = '1.0' + +language = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['.build'] +todo_include_todos = False + +# Syntax highlighting +highlight_language = 'haskell' +pygments_style = 'tango' + +# -- Options for HTML output ---------------------------------------------- + +html_theme = 'alabaster' +htmlhelp_basename = 'Haddockdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { } + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'Haddock.tex', u'Haddock Documentation', + u'Simon Marlow', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'haddock', u'Haddock Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'Haddock', u'Haddock Documentation', + author, 'Haddock', 'One line description of project.', + 'Miscellaneous'), +] + diff --git a/doc/config.mk.in b/doc/config.mk.in deleted file mode 100644 index e286794c..00000000 --- a/doc/config.mk.in +++ /dev/null @@ -1,15 +0,0 @@ -#----------------------------------------------------------------------------- -# DocBook XML stuff - -XSLTPROC = @XsltprocCmd@ -XMLLINT = @XmllintCmd@ -FOP = @FopCmd@ -XMLTEX = @XmltexCmd@ -PDFXMLTEX = @PdfxmltexCmd@ -DVIPS = @DvipsCmd@ - -DIR_DOCBOOK_XSL = @DIR_DOCBOOK_XSL@ - -XSLTPROC_LABEL_OPTS = --stringparam toc.section.depth 3 \ - --stringparam section.autolabel 1 \ - --stringparam section.label.includes.component.label 1 diff --git a/doc/configure.ac b/doc/configure.ac deleted file mode 100644 index acf459e8..00000000 --- a/doc/configure.ac +++ /dev/null @@ -1,12 +0,0 @@ - -AC_INIT([Haddock docs], [1.0], [simonmar@microsoft.com], []) - -AC_CONFIG_SRCDIR([Makefile]) - -dnl ** check for DocBook toolchain -FP_CHECK_DOCBOOK_DTD -FP_DIR_DOCBOOK_XSL([/usr/share/xml/docbook/stylesheet/nwalsh/current /usr/share/xml/docbook/stylesheet/nwalsh /usr/share/sgml/docbook/docbook-xsl-stylesheets* /usr/share/sgml/docbook/xsl-stylesheets* /opt/kde?/share/apps/ksgmltools2/docbook/xsl /usr/share/docbook-xsl /usr/share/sgml/docbkxsl /usr/local/share/xsl/docbook /sw/share/xml/xsl/docbook-xsl /usr/share/xml/docbook/xsl-stylesheets-*]) -FP_PROG_FO_PROCESSOR - -AC_CONFIG_FILES([config.mk]) -AC_OUTPUT diff --git a/doc/docbook-xml.mk b/doc/docbook-xml.mk deleted file mode 100644 index f6048187..00000000 --- a/doc/docbook-xml.mk +++ /dev/null @@ -1,130 +0,0 @@ -#----------------------------------------------------------------------------- -# DocBook XML - -.PHONY: html html-no-chunks chm HxS fo dvi ps pdf - -ifneq "$(XML_DOC)" "" - -all :: html - -# multi-file XML document: main document name is specified in $(XML_DOC), -# sub-documents (.xml files) listed in $(XML_SRCS). - -ifeq "$(XML_SRCS)" "" -XML_SRCS = $(wildcard *.xml) -endif - -XML_HTML = $(addsuffix /index.html,$(basename $(XML_DOC))) -XML_HTML_NO_CHUNKS = $(addsuffix .html,$(XML_DOC)) -XML_CHM = $(addsuffix .chm,$(XML_DOC)) -XML_HxS = $(addsuffix .HxS,$(XML_DOC)) -XML_FO = $(addsuffix .fo,$(XML_DOC)) -XML_DVI = $(addsuffix .dvi,$(XML_DOC)) -XML_PS = $(addsuffix .ps,$(XML_DOC)) -XML_PDF = $(addsuffix .pdf,$(XML_DOC)) - -$(XML_HTML) $(XML_NO_CHUNKS_HTML) $(XML_FO) $(XML_DVI) $(XML_PS) $(XML_PDF) :: $(XML_SRCS) - -html :: $(XML_HTML) -html-no-chunks :: $(XML_HTML_NO_CHUNKS) -chm :: $(XML_CHM) -HxS :: $(XML_HxS) -fo :: $(XML_FO) -dvi :: $(XML_DVI) -ps :: $(XML_PS) -pdf :: $(XML_PDF) - -CLEAN_FILES += $(XML_HTML_NO_CHUNKS) $(XML_FO) $(XML_DVI) $(XML_PS) $(XML_PDF) - -FPTOOLS_CSS = fptools.css - -clean :: - $(RM) -rf $(XML_DOC).out $(basename $(XML_DOC)) $(basename $(XML_DOC))-htmlhelp - -validate :: - $(XMLLINT) --valid --noout $(XMLLINT_OPTS) $(XML_DOC).xml -endif - -#----------------------------------------------------------------------------- -# DocBook XML suffix rules -# - -%.html : %.xml - $(XSLTPROC) --output $@ \ - --stringparam html.stylesheet $(FPTOOLS_CSS) \ - $(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \ - $(DIR_DOCBOOK_XSL)/html/docbook.xsl $< - -%/index.html : %.xml - $(RM) -rf $(dir $@) - $(XSLTPROC) --stringparam base.dir $(dir $@) \ - --stringparam use.id.as.filename 1 \ - --stringparam html.stylesheet $(FPTOOLS_CSS) \ - $(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \ - $(DIR_DOCBOOK_XSL)/html/chunk.xsl $< - cp $(FPTOOLS_CSS) $(dir $@) - -# Note: Numeric labeling seems to be uncommon for HTML Help -%-htmlhelp/index.html : %.xml - $(RM) -rf $(dir $@) - $(XSLTPROC) --stringparam base.dir $(dir $@) \ - --stringparam manifest.in.base.dir 1 \ - --stringparam htmlhelp.chm "..\\"$(basename $<).chm \ - $(XSLTPROC_OPTS) \ - $(DIR_DOCBOOK_XSL)/htmlhelp/htmlhelp.xsl $< - -%-htmlhelp2/collection.HxC : %.xml - $(RM) -rf $(dir $@) - $(XSLTPROC) --stringparam base.dir $(dir $@) \ - --stringparam use.id.as.filename 1 \ - --stringparam manifest.in.base.dir 1 \ - $(XSLTPROC_OPTS) \ - $(DIR_DOCBOOK_XSL)/htmlhelp2/htmlhelp2.xsl $< - -# TODO: Detect hhc & Hxcomp via autoconf -# -# Two obstacles here: -# -# * The reason for the strange "if" below is that hhc returns 0 on error and 1 -# on success, the opposite of what shells and make expect. -# -# * There seems to be some trouble with DocBook indices, but the *.chm looks OK, -# anyway, therefore we pacify make by "|| true". Ugly... -# -%.chm : %-htmlhelp/index.html - ( cd $(dir $<) && if hhc htmlhelp.hhp ; then false ; else true ; fi ) || true - -%.HxS : %-htmlhelp2/collection.HxC - ( cd $(dir $<) && if Hxcomp -p collection.HxC -o ../$@ ; then false ; else true ; fi ) - -%.fo : %.xml - $(XSLTPROC) --output $@ \ - --stringparam draft.mode no \ - $(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \ - $(DIR_DOCBOOK_XSL)/fo/docbook.xsl $< - -ifeq "$(FOP)" "" -ifneq "$(PDFXMLTEX)" "" -%.pdf : %.fo - $(PDFXMLTEX) $< - if grep "LaTeX Warning: Label(s) may have changed.Rerun to get cross-references right." $(basename $@).log > /dev/null ; then \ - $(PDFXMLTEX) $< ; \ - $(PDFXMLTEX) $< ; \ - fi -endif -else -%.ps : %.fo - $(FOP) $(FOP_OPTS) -fo $< -ps $@ - -%.pdf : %.fo - $(FOP) $(FOP_OPTS) -fo $< -pdf $@ -endif - -ifneq "$(XMLTEX)" "" -%.dvi : %.fo - $(XMLTEX) $< - if grep "LaTeX Warning: Label(s) may have changed.Rerun to get cross-references right." $(basename $@).log > /dev/null ; then \ - $(XMLTEX) $< ; \ - $(XMLTEX) $< ; \ - fi -endif diff --git a/doc/fptools.css b/doc/fptools.css deleted file mode 100644 index 5c7fc47b..00000000 --- a/doc/fptools.css +++ /dev/null @@ -1,36 +0,0 @@ -div { - font-family: sans-serif; - color: black; - background: white -} - -h1, h2, h3, h4, h5, h6, p.title { color: #005A9C } - -h1 { font: 170% sans-serif } -h2 { font: 140% sans-serif } -h3 { font: 120% sans-serif } -h4 { font: bold 100% sans-serif } -h5 { font: italic 100% sans-serif } -h6 { font: small-caps 100% sans-serif } - -pre { - font-family: monospace; - border-width: 1px; - border-style: solid; - padding: 0.3em -} - -pre.screen { color: #006400 } -pre.programlisting { color: maroon } - -div.example { - background-color: #fffcf5; - margin: 1ex 0em; - border: solid #412e25 1px; - padding: 0ex 0.4em -} - -a:link { color: #0000C8 } -a:hover { background: #FFFFA8 } -a:active { color: #D00000 } -a:visited { color: #680098 } @@ -10,6 +10,11 @@ # # ----------------------------------------------------------------------------- -utils/haddock/doc_DOCBOOK_SOURCES = utils/haddock/doc/haddock.xml +INSTALL_HTML_DOC_DIRS += utils/haddock/doc/haddock + +html : html_utils/haddock/doc + +html_utils/haddock/doc : + make -C utils/haddock/doc html SPHINX_BUILD=$(SPHINXBUILD) + cp -R utils/haddock/doc/.build-html utils/haddock/doc/haddock -$(eval $(call docbook,utils/haddock/doc,haddock)) 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> diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 00000000..dc30c45f --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,21 @@ +Welcome to Haddock's documentation! +=================================== + +This is Haddock, a tool for automatically generating documentation from +annotated Haskell source code. + +Contents: + +.. toctree:: + :maxdepth: 2 + + intro + invoking + markup + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/doc/intro.rst b/doc/intro.rst new file mode 100644 index 00000000..fcdc67f1 --- /dev/null +++ b/doc/intro.rst @@ -0,0 +1,164 @@ +Introduction +============ + +This is Haddock, a tool for automatically generating documentation from +annotated Haskell source code. Haddock was designed with several goals +in mind: + +- 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. + +- 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. + +- 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 + `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__. In fact, + Haddock can understand IDoc-annotated source code. + +- 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. + + 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. + +- 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. + +- 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. + +Obtaining Haddock +----------------- + +Distributions (source & binary) of Haddock can be obtained from its `web +site <http://www.haskell.org/haddock/>`__. + +Up-to-date sources can also be obtained from our public darcs +repository. The Haddock sources are at +``http://code.haskell.org/haddock``. See +`darcs.net <http://www.darcs.net/>`__ for more information on the darcs +version control utility. + +License +------- + +The following license covers this documentation, and the Haddock source +code, except where otherwise indicated. + + Copyright 2002-2010, Simon Marlow. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + - Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + - Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + + 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. + +Contributors +------------ + +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. + +- Ashley Yakeley +- Benjamin Franksen +- Brett Letner +- Clemens Fruhwirth +- Conal Elliott +- David Waern +- Duncan Coutts +- George Pollard +- George Russel +- Hal Daume +- Ian Lynagh +- Isaac Dupree +- Joachim Breitner +- Krasimir Angelov +- Lennart Augustsson +- Luke Plant +- Malcolm Wallace +- Manuel Chakravarty +- Mark Lentczner +- Mark Shields +- Mateusz Kowalczyk +- Mike Thomas +- Neil Mitchell +- Oliver Brown +- Roman Cheplyaka +- Ross Paterson +- Sigbjorn Finne +- Simon Hengel +- Simon Marlow +- Simon Peyton-Jones +- Stefan O'Rear +- Sven Panne +- Thomas Schilling +- Wolfgang Jeltsch +- Yitzchak Gale + +Acknowledgements +---------------- + +Several documentation systems provided the inspiration for Haddock, most +notably: + +- `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__ + +- `HDoc <http://www.fmi.uni-passau.de/~groessli/hdoc/>`__ + +- `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`__ + +and probably several others I've forgotten. + +Thanks to the the members of haskelldoc@haskell.org, +haddock@projects.haskell.org and everyone who contributed to the many +libraries that Haddock makes use of. diff --git a/doc/invoking.rst b/doc/invoking.rst new file mode 100644 index 00000000..c69c9031 --- /dev/null +++ b/doc/invoking.rst @@ -0,0 +1,458 @@ +Invoking Haddock +================ + +Haddock is invoked from the command line, like so: + +.. code-block:: none + + haddock [option ...] file ... + +Where each ``file`` is a filename containing a Haskell source module (.hs) +or a Literate Haskell source module (.lhs) or just a module name. + +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. + +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. + +The modules should *not* be mutually recursive, as Haddock don't like +swimming in circles. + +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. + +You must also specify an option for the output format. Currently only +the :option:`-h` option for HTML and the :option:`--hoogle` option for outputting +Hoogle data are functional. + +The packaging tool +`Cabal <http://www.haskell.org/ghc/docs/latest/html/Cabal/index.html>`__ +has Haddock support, and is often used instead of invoking Haddock +directly. + +The following options are available: + +.. program:: haddock + +.. option:: -B <dir> + + Tell GHC that that its lib directory is dir. Can be used to override + the default path. + +.. option:: -o <dir> + --odir=<dir> + + Generate files into dir instead of the current directory. + +.. option:: -l <dir> + --lib=<dir> + + Use Haddock auxiliary files (themes, javascript, etc...) in dir. + +.. option:: -i <file> + --read-interface=<file> + -i <docpath>,<file> + --read-interface=<docpath>,<file> + -i <docpath>,<srcpath>,<file> + --read-interface=<docpath>,<srcpath>,<file> + + Read the interface file in file, which must have been produced by + running Haddock with the :option:`--dump-interface` option. The interface + describes a set of modules whose HTML documentation is located in + docpath (which may be a relative pathname). The docpath is optional, + and defaults to “.”. The srcpath is optional but has no default + value. + + This option allows Haddock to produce separate sets of documentation + with hyperlinks between them. The docpath 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 + docpath means that a documentation subtree can still be moved around + without breaking links. + + Similarly to docpath, srcpath is used generate cross-package + hyperlinks but within sources rendered with :option:`--hyperlinked-source` + option. + + Multiple :option:`--read-interface` options may be given. + +.. option:: -D <file> + --dump-interface=<file> + + Produce an interface file [1]_ in the file file. 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 for more details. The interface file is + in a binary format; don't try to read it. + +.. [1] + Haddock interface files are not the same as Haskell interface files, + I just couldn't think of a better name. + +.. option:: -h + --html + + Generate documentation in HTML format. Several files will be + generated into the current directory (or the specified directory if + the :option:`-o` option is given), including the following: + + ``module.html``; ``mini_module.html`` + An HTML page for each module, and a "mini" page for each used + when viewing in frames. + + ``index.html`` + The top level page of the documentation: lists the modules + available, using indentation to represent the hierarchy if the + modules are hierarchical. + + ``doc-index.html``; ``doc-index-X.html`` + The alphabetic index, possibly split into multiple pages if big + enough. + + ``frames.html`` + The top level document when viewing in frames. + + ``some.css``; ``etc...`` + Files needed for the themes used. Specify your themes using the + :option:`--theme` option. + + ``haddock-util.js`` + Some JavaScript utilities used to implement some of the dynamic + features like collapsible sections, and switching to frames + view. + +.. option:: --latex + + Generate documentation in LaTeX format. Several files will be + generated into the current directory (or the specified directory if + the :option:`-o` option is given), including the following: + + ``package.tex`` + The top-level LaTeX source file; to format the documentation + into PDF you might run something like this: :: + + $ pdflatex package.tex + + ``haddock.sty`` + 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. + + ``module.tex`` + The LaTeX documentation for each module. + +.. option:: --latex-style=<style> + + This option lets you override the default style used by the LaTeX + generated by the :option:`--latex` option. Normally Haddock puts a + standard ``haddock.sty`` in the output directory, and includes the + command ``\usepackage{haddock}`` in the LaTeX source. If this option + is given, then ``haddock.sty`` is not generated, and the command is + instead ``\usepackage{style}``. + +.. option:: --hyperlinked-source + + Generate hyperlinked source code (as HTML web page). All rendered + files will be put into ``src/`` subfolder of output directory. + + Usually, this should be used in combination with :option:`--html` 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:`--source-module`, :option:`--source-entity` and + related options. Note that these flags are ignored once + :option:`--hyperlinked-source` is set. + + 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:: --source-css=<style> + + Use custom CSS file for sources rendered by the + :option:`--hyperlinked-source` option. If no custom style file is + provided, Haddock will use default one. + +.. option:: -S, --docbook + + Reserved for future use (output documentation in DocBook XML + format). + +.. option:: --source-base=<url> + --source-module=<url> + --source-entity=<url> + --source-entity-line=<url> + + Include links to the source files in the generated documentation. + Use the :option:`--source-base` option to add a source code link in the + header bar of the contents and index pages. Use the + :option:`--source-module` to add a source code link in the header bar of + each module page. Use the :option:`--source-entity` option to add a source + code link next to the documentation for every value and type in each + module. :option:`--source-entity-line` 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. + + In each case URL 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 URL: + + - The string ``%M`` or ``%{MODULE}`` is replaced by the module + name. Note that for the per-entity URLs this is the name of the + *exporting* module. + + - The string ``%F`` or ``%{FILE}`` is replaced by the original + source file name. Note that for the per-entity URLs this is the + name of the *defining* module. + + - The string ``%N`` or ``%{NAME}`` is replaced by the name of the + exported value or type. This is only valid for the + :option:`--source-entity` option. + + - The string ``%K`` or ``%{KIND}`` is replaced by a flag indicating + whether the exported name is a value ``v`` or a type + ``t``. This is only valid for the :option:`--source-entity` option. + + - The string ``%L`` or ``%{LINE}`` 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. + + - The string ``%%`` is replaced by ``%``. + + For example, if your sources are online under some directory, you + would say ``haddock --source-base=url/ --source-module=url/%F`` + + If you have html versions of your sources online with anchors for + each type and function name, you would say + ``haddock --source-base=url/ --source-module=url/%M.html --source-entity=url/%M.html#%N`` + + For the ``%{MODULE}`` substitution you may want to replace the + ``.`` character in the module names with some other character + (some web servers are known to get confused by multiple ``.`` + characters in a file name). To replace it with a character c use + ``%{MODULE/./c}``. + + Similarly, for the ``%{FILE}`` substitution you may want to replace + the ``/`` 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 c use ``%{FILE///c}``/ + + One example of a tool that can generate syntax-highlighted HTML from + your source code, complete with anchors suitable for use from + haddock, is + `hscolour <http://www.cs.york.ac.uk/fp/darcs/hscolour>`__. + +.. option:: -s <url> + --source=<url> + + Deprecated aliases for :option:`--source-module` + +.. option:: --comments-base=<url> + --comments-module=<url> + --comments-entity=<url> + + documentation. This feature would typically be used in conjunction + with a Wiki system. + + Use the :option:`--comments-base` option to add a user comments link in + the header bar of the contents and index pages. Use the + :option:`--comments-module` to add a user comments link in the header bar + of each module page. Use the :option:`--comments-entity` option to add a + comments link next to the documentation for every value and type in + each module. + + In each case URL 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` and + :option:`--source-entity` options above. + + For example, if you want to link the contents page to a wiki page, + and every module to subpages, you would say + ``haddock --comments-base=url --comments-module=url/%M`` + + If your Wiki system doesn't like the ``.`` character in Haskell + module names, you can replace it with a different character. For + example to replace the ``.`` characters with ``_`` use + ``haddock --comments-base=url --comments-module=url/%{MODULE/./_}``. + Similarly, you can replace the ``/`` in a file name (may be useful for + entity comments, but probably not). + +.. option:: --theme=<path> + + Specify a theme to be used for HTML (:option:`--html`) 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. + + The path parameter can be one of: + + - A *directory*: The base name of the directory becomes the name of + the theme. The directory must contain exactly one ``some.css`` + file. Other files, usually image files, will be copied, along + with the ``some.css`` file, into the generated output directory. + + - A *CSS file*: The base name of the file becomes the name of the + theme. + + - The *name* of a built-in theme ("Ocean" or "Classic"). + +.. option:: --built-in-themes + + Includes the built-in themes ("Ocean" and "Classic"). Can be + combined with :option:`--theme`. Note that order matters: The first + specified theme will be the default. + +.. option:: --use-unicode + + Enable use of Unicode characters in HTML output. + +.. option:: -c <file> + --css=<file> + + Deprecated aliases for :option:`--theme` + +.. option:: -p <file> + --prologue=<file> + + 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). + +.. option:: -t <title> + --title=<title> + + Use title as the page heading for each page in the + documentation.This will normally be the name of the library being + documented. + + The title should be a plain string (no markup please!). + +.. option:: -q <mode> + --qual=<mode> + + Specify how identifiers are qualified. + + mode should be one of + + - ``none`` (default): don't qualify any identifiers + + - ``full``: always qualify identifiers completely + + - ``local``: only qualify identifiers that are not part of the module + + - ``relative``: like local, but strip name of the module from + qualifications of identifiers in submodules + + Example: If you generate documentation for module A, then the + identifiers A.x, A.B.y and C.z are qualified as follows. + + - none: x, y, z + + - full: A.x, A.B.y, C.z + + - local: x, A.B.y, C.z + + - relative: x, B.y, C.z + +.. option:: -? + --help + + Display help and exit. + +.. option:: -V + --version + + Output version information and exit. + +.. option:: -v + --verbose + + 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 ``Prelude``). + +.. option:: --use-contents=<url> + --use-index=<url> + + When generating HTML, do not generate an index. Instead, redirect + the Contents and/or Index link on each page to URL. This option is + intended for use in conjunction with :option:`--gen-contents` and/or + :option:`--gen-index` for generating a separate contents and/or index + covering multiple libraries. + +.. option:: --gen-contents + --gen-index + + Generate an HTML contents and/or index containing entries pulled + from all the specified interfaces (interfaces are specified using + :option:`-i` or :option:`--read-interface`). This is used to generate a single + contents and/or index for multiple sets of Haddock documentation. + +.. option:: --ignore-all-exports + + Causes Haddock to behave as if every module has the + ``ignore-exports`` attribute (:ref:`module-attrs`). This might be useful for + generating implementation documentation rather than interface + documentation, for example. + +.. option:: --hide <module> + + Causes Haddock to behave as if module module has the ``hide`` + attribute. (:ref:`module-attrs`). + +.. option:: --show-extensions <module> + + Causes Haddock to behave as if module module has the + ``show-extensions`` attribute. (:ref:`module-attrs`). + +.. option:: --optghc=<option> + + Pass option to GHC. Note that there is a double dash there, unlike + for GHC. + +.. option:: -w + --no-warnings + + Turn off all warnings. + +.. option:: --compatible-interface-versions + + Prints out space-separated versions of binary Haddock interface + files that this version is compatible with. + +.. option:: --no-tmp-comp-dir + + Do not use a temporary directory for reading and writing compilation + output files (``.o``, ``.hi``, and stub files). Instead, use the + present directory or another directory that you have explicitly told + GHC to use via the :option:`--optghc` flag. + + 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. + +.. option:: --print-missing-docs + + Print extra information about any undocumented entities. + +Using literate or pre-processed source +-------------------------------------- + +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 to GHC using :option:`--optghc`. + diff --git a/doc/markup.rst b/doc/markup.rst new file mode 100644 index 00000000..a2274ad6 --- /dev/null +++ b/doc/markup.rst @@ -0,0 +1,887 @@ +Documentation and Markup +======================== + +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. + +Documenting a top-level declaration +----------------------------------- + +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: :: + + square :: Int -> Int + square x = x * x + +Then we can document it like this: :: + + -- |The 'square' function squares an integer. + square :: Int -> Int + square x = x * x + +The ``-- |`` syntax begins a documentation annotation, which applies +to the *following* declaration in the source file. Note that the +annotation is just a comment in Haskell — it will be ignored by the +Haskell compiler. + +The declaration following a documentation annotation should be one of +the following: + +- A type signature for a top-level function, + +- A ``data`` declaration, + +- A ``newtype`` declaration, + +- A ``type`` declaration + +- A ``class`` declaration, + +- A ``data family`` or ``type family`` declaration, or + +- A ``data instance`` or ``type instance`` declaration. + +If the annotation is followed by a different kind of declaration, it +will probably be ignored by Haddock. + +Some people like to write their documentation *after* the declaration; +this is possible in Haddock too: :: + + square :: Int -> Int + -- ^The 'square' function squares an integer. + square x = x * x + +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. + +Documentation annotations may span several lines; the annotation +continues until the first non-comment line in the source file. For +example: :: + + -- |The 'square' function squares an integer. + -- It takes one argument, of type 'Int'. + square :: Int -> Int + square x = x * x + +You can also use Haskell's nested-comment style for documentation +annotations, which is sometimes more convenient when using multi-line +comments: :: + + {-| + The 'square' function squares an integer. + It takes one argument, of type 'Int'. + -} + square :: Int -> Int + square x = x * x + +Documenting parts of a declaration +---------------------------------- + +In addition to documenting the whole declaration, in some cases we can +also document individual parts of the declaration. + +Class methods +~~~~~~~~~~~~~ + +Class methods are documented in the same way as top level type +signatures, by using either the ``-- |`` or ``-- ^`` annotations: :: + + 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 + +Constructors and record fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Constructors are documented like so: :: + + 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 + +or like this: :: + + 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 + +Record fields are documented using one of these styles: :: + + 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 + } + +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. + +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. :: + + data T a = A { someField :: a -- ^ Doc for someField of A + } + | B { someField :: a -- ^ Doc for someField of B + } + +In the above example, all occurences of ``someField`` in the +documentation are going to be documented with +``Doc for someField of A``. 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 ``someField`` +is actually the same (partial) function. + +Function arguments +~~~~~~~~~~~~~~~~~~ + +Individual arguments to a function may be documented like this: :: + + f :: Int -- ^ The 'Int' argument + -> Float -- ^ The 'Float' argument + -> IO () -- ^ The return value + +The module description +---------------------- + +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. :: + + {-| + 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 + ... + +The “Module” 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. + +The “Description” 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. + +The “Copyright”, “License”, “Maintainer” and “Stability” fields should +be obvious. An alternative spelling for the “License” field is accepted +as “Licence” but the output will always prefer “License”. + +The “Portability” 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 “show-extensions” module +flag for the latter. + +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 “Description” in the documentation for the module. All usual +Haddock markup is valid in this comment. + +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 “--” 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. + +Controlling the documentation structure +--------------------------------------- + +Haddock produces interface documentation that lists only the entities +actually exported by the module. The documentation for a module will +include *all* 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. + +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 *order* that entities will be listed in the generated +documentation. This leaves the programmer free to implement functions in +any order he/she pleases, and indeed in any *module* he/she pleases, but +still specify the order that the functions should be documented in the +export list. Indeed, many programmers already do this: the export list +is often used as a kind of ad-hoc interface documentation, with +headings, groups of functions, type signatures and declarations in +comments. + +You can insert headings and sub-headings in the documentation by +including annotations at the appropriate point in the export list. For +example: :: + + module Foo ( + -- * Classes + C(..), + -- * Types + -- ** A data type + T, + -- ** A record + R, + -- * Some functions + f, g + ) where + +Headings are introduced with the syntax ``-- *``, ``-- **`` and so +on, where the number of ``*``\ s indicates the level of the heading +(section, sub-section, sub-sub-section, etc.). + +If you use section headings, then Haddock will generate a table of +contents at the top of the module documentation for you. + +The alternative style of placing the commas at the beginning of each +line is also supported. e.g.: :: + + module Foo ( + -- * Classes + , C(..) + -- * Types + -- ** A data type + , T + -- ** A record + , R + -- * Some functions + , f + , g + ) where + +Re-exporting an entire module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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: :: + + module A ( + module B, + module C + ) where + +What will the Haddock-generated documentation for this module look like? +Well, it depends on how the modules ``B`` and ``C`` are imported. If +they are imported wholly and without any ``hiding`` qualifiers, then the +documentation will just contain a cross-reference to the documentation +for ``B`` and ``C``. However, if the modules are not *completely* +re-exported, for example: :: + + module A ( + module B, + module C + ) where + + import B hiding (f) + import C (a, b) + +then Haddock behaves as if the set of entities re-exported from ``B`` +and ``C`` had been listed explicitly in the export list [2]_. + +.. [2] + NOTE: this is not fully implemented at the time of writing (version + 0.2). At the moment, Haddock always inserts a cross-reference. + +The exception to this rule is when the re-exported module is declared +with the ``hide`` attribute (:ref:`module-attrs`), in which case the module is +never cross-referenced; the contents are always expanded in place in the +re-exporting module. + +Omitting the export list +~~~~~~~~~~~~~~~~~~~~~~~~ + +If there is no export list in the module, how does Haddock generate +documentation? Well, when the export list is omitted, e.g.: :: + + module Foo where + +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). :: + + module Foo where + + -- * This heading will now appear before foo. + + -- | Documentation for 'foo'. + foo :: Integer + foo = 5 + +Named chunks of documentation +----------------------------- + +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: + +- The documentation can be included in the export list directly, e.g.: :: + + module Foo ( + -- * A section heading + + -- | Some documentation not attached to a particular Haskell entity + ... + ) where + +- 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 + “``-- $``”: :: + + module Foo ( + -- * A section heading + + -- $doc + ... + ) where + + -- $doc + -- Here is a large chunk of documentation which may be referred to by + -- the name $doc. + + The documentation chunk is given a name, which is the sequence of + alphanumeric characters directly after the “``-- $``”, and it may be + referred to by the same name in the export list. + +Hyperlinking and re-exported entities +------------------------------------- + +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? + +Let's look at an example. Suppose we have three modules ``A``, ``B`` and +``C`` defined as follows: :: + + 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 + +Module ``A`` exports a datatype ``T``. Module ``B`` imports ``A`` and +exports a function ``f`` whose type refers to ``T``. Also, both ``T`` +and ``f`` are re-exported from module C. + +Haddock takes the view that each entity has a *home* module; that is, +the module that the library designer would most like to direct the user +to, to find the documentation for that entity. So, Haddock makes all +links to an entity point to the home module. The one exception is when +the entity is also exported by the current module: Haddock makes a local +link if it can. + +How is the home module for an entity determined? Haddock uses the +following rules: + +- If modules A and B both export the entity, and module A imports + (directly or indirectly) module B, then B is preferred. + +- A module with the ``hide`` attribute is never chosen as the home. + +- A module with the ``not-home`` attribute is only chosen if there are + no other modules to choose. + +If multiple modules fit the criteria, then one is chosen at random. If +no modules fit the criteria (because the candidates are all hidden), +then Haddock will issue a warning for each reference to an entity +without a home. + +In the example above, module ``A`` is chosen as the home for ``T`` +because it does not import any other module that exports ``T``. The link +from ``f``'s type in module ``B`` will therefore point to ``A.T``. +However, ``C`` also exports ``T`` and ``f``, and the link from ``f``'s +type in ``C`` will therefore point locally to ``C.T``. + +.. _module-attrs: + +Module Attributes +----------------- + +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 +``{-# OPTIONS_HADDOCK ... #-}`` pragma at the top of the module, either +before or after the module description. For example: :: + + {-# OPTIONS_HADDOCK hide, prune, ignore-exports #-} + + -- |Module description + module A where + ... + +The options and module description can be in either order. + +The following attributes are currently understood by Haddock: + +``hide`` ``hide`` + Omit this module from the generated documentation, but nevertheless + propagate definitions and documentation from within this module to + modules that re-export those definitions. + +``hide`` ``prune`` + Omit definitions that have no documentation annotations from the + generated documentation. + +``ignore-exports`` ``ignore-exports`` + Ignore the export list. Generate documentation as if the module had + no export list - i.e. all the top-level declarations are exported, + and section headings may be given in the body of the module. + +``not-home`` ``not-home`` + Indicates that the current module should not be considered to be the + home module for each entity it exports, unless that entity is not + exported from any other module. See ? for more details. + +``show-extensions`` ``show-extensions`` + Indicates that we should render the extensions used in this module + in the resulting documentation. This will only render if the output + format supports it. If Language is set, it will be shown as well and + all the extensions implied by it won't. All enabled extensions will + be rendered, including those implied by their more powerful + versions. + +Markup +------ + +Haddock understands certain textual cues inside documentation +annotations that tell it how to render the documentation. The cues (or +“markup”) 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. + +Paragraphs +~~~~~~~~~~ + +One or more blank lines separates two paragraphs in a documentation +comment. + +Special characters +~~~~~~~~~~~~~~~~~~ + +The following characters have special meanings in documentation +comments: ``\\``, ``/``, ``'``, ``\```, ``"``, ``@``, ``<``. To insert a +literal occurrence of one of these special characters, precede it with a +backslash (``\\``). + +Additionally, the character ``>`` has a special meaning at the beginning +of a line, and the following characters have special meanings at the +beginning of a paragraph: ``*``, ``-``. These characters can also be +escaped using ``\\``. + +Furthermore, the character sequence ``>>>`` has a special meaning at the +beginning of a line. To escape it, just prefix the characters in the +sequence with a backslash. + +Character references +~~~~~~~~~~~~~~~~~~~~ + +Although Haskell source files may contain any character from the Unicode +character set, the encoding of these characters as bytes varies between +systems, so that only source files restricted to the ASCII character set +are portable. Other characters may be specified in character and string +literals using Haskell character escapes. To represent such characters +in documentation comments, Haddock supports SGML-style numeric character +references of the forms ``&#``\ D\ ``;`` and ``&#x``\ H\ ``;`` where D +and H are decimal and hexadecimal numbers denoting a code position in +Unicode (or ISO 10646). For example, the references ``λ``, +``λ`` and ``λ`` all represent the lower-case letter lambda. + +Code Blocks +~~~~~~~~~~~ + +Displayed blocks of code are indicated by surrounding a paragraph with +``@...@`` or by preceding each line of a paragraph with ``>`` (we often +call these “bird tracks”). For example: :: + + -- | This documentation includes two blocks of code: + -- + -- @ + -- f x = x + x + -- @ + -- + -- > g x = x * 42 + +There is an important difference between the two forms of code block: in +the bird-track form, the text to the right of the ‘\ ``>``\ ’ is +interpreted literally, whereas the ``@...@`` form interprets markup as +normal inside the code block. + +Examples +~~~~~~~~ + +Haddock has markup support for examples of interaction with a +*read-eval-print loop (REPL)*. An example is introduced with ``>>>`` +followed by an expression followed by zero or more result lines: :: + + -- | Two examples are given below: + -- + -- >>> fib 10 + -- 55 + -- + -- >>> putStrLn "foo\nbar" + -- foo + -- bar + +Result lines that only contain the string ``<BLANKLINE>`` are rendered +as blank lines in the generated documentation. + +Properties +~~~~~~~~~~ + +Haddock provides markup for properties: :: + + -- | Addition is commutative: + -- + -- prop> a + b = b + a + +This allows third-party applications to extract and verify them. + +Hyperlinked Identifiers +~~~~~~~~~~~~~~~~~~~~~~~ + +Referring to a Haskell identifier, whether it be a type, class, +constructor, or function, is done by surrounding it with single quotes: :: + + -- | This module defines the type 'T'. + +If there is an entity ``T`` in scope in the current module, then the +documentation will hyperlink the reference in the text to the definition +of ``T`` (if the output format supports hyperlinking, of course; in a +printed format it might instead insert a page reference to the +definition). + +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: :: + + -- | The identifier 'M.T' is not in scope + +If ``M.T`` is not otherwise in scope, then Haddock will simply emit a +link pointing to the entity ``T`` exported from module ``M`` (without +checking to see whether either ``M`` or ``M.T`` exist). + +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: :: + + -- | I don't have to escape my apostrophes; great, isn't it? + +Nothing special is needed to hyperlink identifiers which contain +apostrophes themselves: to hyperlink ``foo'`` one would simply type +``'foo''``. To hyperlink identifiers written in infix form, simply put +them in quotes as always: ``'`elem`'``. + +For compatibility with other systems, the following alternative form of +markup is accepted [3]_: ```T'``. + +.. [3] + We chose not to use this as the primary markup for identifiers + because strictly speaking the ````` character should not be used as a + left quote, it is a grave accent. + +Emphasis, Bold and Monospaced text +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Emphasis may be added by surrounding text with ``/.../``. Other markup +is valid inside emphasis. To have a forward slash inside of emphasis, +just escape it: ``/fo\/o/`` + +Bold (strong) text is indicated by surrounding it with ``__...__``. +Other markup is valid inside bold. For example, ``__/foo/__`` will make +the emphasised text ``foo`` bold. You don't have to escape a single +underscore if you need it bold: +``__This_text_with_underscores_is_bold__``. + +Monospaced (or typewriter) text is indicated by surrounding it with +``@...@``. Other markup is valid inside a monospaced span: for example +``@'f' a b@`` will hyperlink the identifier ``f`` inside the code +fragment. + +Linking to modules +~~~~~~~~~~~~~~~~~~ + +Linking to a module is done by surrounding the module name with double +quotes: :: + + -- | This is a reference to the "Foo" module. + +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. + +Itemized and Enumerated lists +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A bulleted item is represented by preceding a paragraph with either +“``*``” or “``-``”. A sequence of bulleted paragraphs is rendered as an +itemized list in the generated documentation, eg.: :: + + -- | This is a bulleted list: + -- + -- * first item + -- + -- * second item + +An enumerated list is similar, except each paragraph must be preceded by +either “``(n)``” or “``n.``” where n is any integer. e.g. :: + + -- | This is an enumerated list: + -- + -- (1) first item + -- + -- 2. second item + +Lists of the same type don't have to be separated by a newline: :: + + -- | This is an enumerated list: + -- + -- (1) first item + -- 2. second item + -- + -- This is a bulleted list: + -- + -- * first item + -- * second item + +You can have more than one line of content in a list element: :: + + -- | + -- * first item + -- and more content for the first item + -- * second item + -- and more content for the second item + +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: :: + + {-| + * 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. + -} + +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. :: + + {-| + * foo + + * bar + -} + +Definition lists +~~~~~~~~~~~~~~~~ + +Definition lists are written as follows: :: + + -- | This is a definition list: + -- + -- [@foo@]: The description of @foo@. + -- + -- [@bar@]: The description of @bar@. + +To produce output something like this: + +``foo`` + The description of ``foo``. + +``bar`` + The description of ``bar``. + +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 ``]`` with a +backslash as usual. + +Same rules about nesting and no newline separation as for bulleted and +numbered lists apply. + +URLs +~~~~ + +A URL can be included in a documentation comment by surrounding it in +angle brackets, for example: :: + + <http://example.com> + +If the output format supports it, the URL will be turned into a +hyperlink when rendered. + +If Haddock sees something that looks like a URL (such as something +starting with ``http://`` or ``ssh://``) where the URL markup is valid, +it will automatically make it a hyperlink. + +Links +~~~~~ + +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: :: + + [some link](http://example.com) + +The link text is used as a descriptive text for the URL, if the output +format supports it. + +Images +~~~~~~ + +Haddock supports Markdown syntax for inline images. This resembles the +syntax for links, but starts with an exclamation mark. An example looks +like this: :: + +  + +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. + +Anchors +~~~~~~~ + +Sometimes it is useful to be able to link to a point in the +documentation which doesn't correspond to a particular entity. For that +purpose, we allow *anchors* to be included in a documentation comment. +The syntax is ``#label#``, where label is the name of the anchor. An +anchor is invisible in the generated documentation. + +To link to an anchor from elsewhere, use the syntax ``"module#label"`` +where module is the module name containing the anchor, and label is the +anchor label. The module does not have to be local, it can be imported +via an interface. Please note that in Haddock versions 2.13.x and +earlier, the syntax was ``"module\#label"``. It is considered deprecated +and will be removed in the future. + +Headings +~~~~~~~~ + +Headings inside of comment documentation are possible be preceding them +with a number of ``=``\ s. From 1 to 6 are accepted. Extra ``=``\ 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. :: + + -- | + -- = Heading level 1 with some /emphasis/ + -- Something underneath the heading. + -- + -- == /Subheading/ + -- More content. + -- + -- === Subsubheading + -- Even more content. + +Note that while headings have to start on a new paragraph, we allow +paragraph-level content to follow these immediately. :: + + -- | + -- = Heading level 1 with some __bold__ + -- Something underneath the heading. + -- + -- == /Subheading/ + -- More content. + -- + -- === Subsubheading + -- >>> examples are only allowed at the start of paragraphs + +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 ``=``\ s. :: + + -- | + -- === __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. + +Metadata +~~~~~~~~ + +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. + +Since +^^^^^ + +``@since`` 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. ``@since`` 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. ``@since`` 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. :: + + -- | + -- Some comment + -- + -- @since 1.2.3 |