diff options
Diffstat (limited to 'doc/haddock.xml')
| -rw-r--r-- | doc/haddock.xml | 157 |
1 files changed, 125 insertions, 32 deletions
diff --git a/doc/haddock.xml b/doc/haddock.xml index 39a947ca..2ffd7d78 100644 --- a/doc/haddock.xml +++ b/doc/haddock.xml @@ -1,6 +1,14 @@ <?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"> + "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> @@ -21,7 +29,7 @@ <holder>Simon Marlow, David Waern</holder> </copyright> <abstract> - <para>This document describes Haddock version 2.15.0, a Haskell + <para>This document describes Haddock version 2.15.1, a Haskell documentation tool.</para> </abstract> </bookinfo> @@ -1033,6 +1041,18 @@ $ pdflatex <replaceable>package</replaceable>.tex</screen> </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"> @@ -1877,7 +1897,9 @@ module A where <para>Nothing special is needed to hyperlink identifiers which contain apostrophes themselves: to hyperlink <literal>foo'</literal> one would simply type - <literal>'foo''</literal>.</para> + <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> @@ -2018,9 +2040,9 @@ This belongs to the list above! <programlisting> -- | This is a definition list: -- --- [@foo@] The description of @foo@. +-- [@foo@]: The description of @foo@. -- --- [@bar@] The description of @bar@. +-- [@bar@]: The description of @bar@. </programlisting> <para>To produce output something like this:</para> @@ -2041,13 +2063,8 @@ This belongs to the list above! </variablelist> <para>Each paragraph should be preceded by the - “definition term” enclosed in square brackets. - The square bracket characters have no special meaning outside - the beginning of a definition paragraph. That is, if a - paragraph begins with a <literal>[</literal> character, then - it is assumed to be a definition paragraph, and the next - <literal>]</literal> character found will close the definition - term. Other markup operators may be used freely within 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. @@ -2058,37 +2075,60 @@ This belongs to the list above! <section> <title>URLs</title> - <para>A URL can be included in a documentation comment by - surrounding it in angle brackets: - <literal><...></literal>. If the output format supports - it, the URL will be turned into a hyperlink when - rendered.</para> + <para> + A URL can be included in a documentation comment by surrounding it in + angle brackets, for example: + </para> - <para>The URL can be followed by an optional label:</para> <programlisting> -<http://example.com label> +<http://example.com> </programlisting> - <para>The label is then used as a descriptive text for the hyperlink, if the - output format supports it.</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> + <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>Images</title> + <title>Links</title> - <para>An image can be included in a documentation comment by - surrounding it in double angle brackets: - <literal><<...>></literal>. If the output format supports - it, the image will be rendered inside the documentation.</para> + <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> - <para>Title text can be included using an optional label:</para> <programlisting> -<<pathtoimage.png title>> +[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> @@ -2123,7 +2163,7 @@ This belongs to the list above! <programlisting> -- | --- = Heading level 1 with some __bold__ +-- = Heading level 1 with some /emphasis/ -- Something underneath the heading. -- -- == /Subheading/ @@ -2149,6 +2189,59 @@ This belongs to the list above! -- >>> 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> |