From 15e1d576d1dbede8041452272a5077b66d843255 Mon Sep 17 00:00:00 2001 From: Mateusz Kowalczyk Date: Fri, 20 Sep 2013 11:32:00 +0100 Subject: Update documentation. --- CHANGES | 29 ++++-- doc/haddock.xml | 318 ++++++++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 271 insertions(+), 76 deletions(-) diff --git a/CHANGES b/CHANGES index 13e1d269..3e7e8a2f 100644 --- a/CHANGES +++ b/CHANGES @@ -12,6 +12,19 @@ Changes in version 2.14.0 * Improved to Unicode support + * Bold markup support + + * Nested paragraphs + + * Better escaping + + * Header markup + + * Parser should no longer fail to parse any markup + + * {-# OPTIONS_HADDOCK show-extensions #-} pragma will show the GHC extensions + enabled in the module. + Changes in version 2.13.2 * Handle HsExplicitListTy in renamer (#213) @@ -121,7 +134,7 @@ Changes in version 2.9.0 * Minor changes to the API Changes in the version that comes with GHC 7.0.1 - + [This version claims it is 2.8.0 but is actually based on 2.8.1] * Fix URL creation on Windows: Use / not \ in URLs. @@ -267,7 +280,7 @@ Changed in version 2.4.2: (#65) * Fixes to the Hoogle backend - + * Improvements to the haddock library * Many other fixes (including #67, #69, #58, #57) @@ -358,7 +371,7 @@ Changes in version 2.0.0.0: in GHC 6.8.2 * Format of module attributes has changed. The only way of specifiying - module attributes is via a new OPTIONS_HADDOCK pragma. Example: + module attributes is via a new OPTIONS_HADDOCK pragma. Example: {-# OPTIONS_HADDOCK hide, prune #-} * Haddock understands literate source files @@ -474,7 +487,7 @@ Changes in version 0.6: now turned off by default; Haddock should be a little less noisy in general. - * Markup for definition lists has been added. See the documentation + * Markup for definition lists has been added. See the documentation for details. * New option: --package for setting the package name. The package @@ -514,7 +527,7 @@ Changes in version 0.4: which describe the exports of a set of modules. This is useful for generating documentation which hyperlinks to previously-generated documentation. - + * Support for generating the extra files required by the Microsoft Help compiler. @@ -525,9 +538,9 @@ Changes in version 0.4: ----------------------------------------------------------------------------- Changes in version 0.3: - - * Documentation on individual function arguments is now implemented - + + * Documentation on individual function arguments is now implemented + * Links can be made to identifiers that aren't in scope, by using the fully qualified name. diff --git a/doc/haddock.xml b/doc/haddock.xml index 4e51cc6c..b5331c26 100644 --- a/doc/haddock.xml +++ b/doc/haddock.xml @@ -58,7 +58,7 @@ Documentation annotations in the source code should be easy on the eye when editing the source code itself, so as not - to obsure the code and to make reading and writing + 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, @@ -170,40 +170,41 @@ 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 - Mark Lentczner - Mark Shields - Neil Mitchell - Mike Thomas - Manuel Chakravarty - Oliver Brown - Roman Cheplyaka - Ross Paterson - Simon Hengel - Simon Marlow - Simon Peyton-Jones - Sigbjorn Finne - Stefan O'Rear - Sven Panne - Thomas Schilling - Wolfgang Jeltsch - Yitzchak Gale + 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
@@ -262,11 +263,14 @@ 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 - indentifiers it couldn't resolve. + 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 for HTML and the option for outputting Hoogle data are @@ -435,7 +439,7 @@ haddock-util.js Some JavaScript utilities used to implement some of the - dynamic features like collapsable sections, and switching to + dynamic features like collapsible sections, and switching to frames view. @@ -453,7 +457,7 @@ will be generated into the current directory (or the specified directory if the option is given), including the following: - + package.tex @@ -544,7 +548,7 @@ $ pdflatex package.tex option to add a source code link next to the documentation for every value and type in each module. - + 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 @@ -590,7 +594,7 @@ $ pdflatex package.tex 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/ @@ -650,7 +654,7 @@ $ pdflatex package.tex Include links to pages where readers may comment on the documentation. This feature would typically be used in conjunction with a Wiki system. - + Use the option to add a user comments link in the header bar of the contents and index pages. Use the to add a user comments @@ -658,7 +662,7 @@ $ pdflatex package.tex 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 @@ -669,7 +673,7 @@ $ pdflatex package.tex 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 @@ -692,12 +696,12 @@ $ pdflatex package.tex 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 + 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: @@ -825,16 +829,16 @@ $ pdflatex package.tex - none: x, y, z + none: x, y, z - full: A.x, A.B.y, C.z + full: A.x, A.B.y, C.z - local: x, A.B.y, C.z + local: x, A.B.y, C.z - relative: x, B.y, C.z + relative: x, B.y, C.z @@ -900,7 +904,7 @@ $ pdflatex package.tex 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 conjuction with and/or + use in conjunction with and/or for generating a separate contents and/or index covering multiple libraries. @@ -917,10 +921,10 @@ $ pdflatex package.tex - Generate an HTML contents and/or index containing entries pulled + Generate an HTML contents and/or index containing entries pulled from all the specified interfaces (interfaces are specified using or ). - This is used to generate a single contents and/or index for multiple + This is used to generate a single contents and/or index for multiple sets of Haddock documentation. @@ -932,7 +936,7 @@ $ pdflatex package.tex - Causes Haddock to behaves as if every module has the + Causes Haddock to behave as if every module has the ignore-exports attribute (). This might be useful for generating implementation documentation rather than interface @@ -947,19 +951,32 @@ $ pdflatex package.tex  module - Causes Haddock to behaves as if module + Causes Haddock to behave as if module module has the hide - atribute. (). + attribute. (). + + + + + + + +  module + + + Causes Haddock to behave as if module + module has the show-extensions + attribute. (). - + =option - Pass option to GHC. + Pass option to GHC. Note that there is a double dash there, unlike for GHC. @@ -977,6 +994,19 @@ $ pdflatex package.tex + + + + + + + + Prints out space-separated versions of binary Haddock interface files that this version is compatible + with. + + + + @@ -992,7 +1022,7 @@ $ pdflatex package.tex 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. + Template Haskell, in which case Haddock compiles the modules using the GHC API. @@ -1001,10 +1031,10 @@ $ pdflatex package.tex
Using literate or pre-processed source - Since Haddock uses GHC internally, both plain and + 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 to GHC + the user must pass the the option to GHC using .
@@ -1349,6 +1379,17 @@ import C (a, b) 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 + +
@@ -1461,7 +1502,7 @@ import B chosen as the home. - A module with the not-home atribute is only + A module with the not-home attribute is only chosen if there are no other modules to choose. @@ -1555,6 +1596,20 @@ module A where 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. + + + @@ -1669,7 +1724,7 @@ module A where Result lines that only contain the string <BLANKLINE> are rendered as blank lines in the - generated documenation. + generated documentation.
@@ -1736,10 +1791,17 @@ module A where
- Emphasis and Monospaced text + 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 @@ -1758,6 +1820,11 @@ module A where -- | 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. + +
@@ -1791,6 +1858,59 @@ module A where -- -- 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. +-} + +
@@ -1831,7 +1951,11 @@ module A where it is assumed to be a definition paragraph, and the next ] character found will close the definition term. Other markup operators may be used freely within the - definition term. + 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. + +
@@ -1843,12 +1967,31 @@ module A where it, the URL will be turned into a hyperlink when rendered. - The URL can be followed by an optional label: + The URL can be followed by an optional label: <http://example.com label> - The label is then used as a descriptive text for the hyperlink, if the - output format supports it. + The label is then used as a descriptive text for the hyperlink, if the + output format supports it. + + 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. +
+ +
+ Images + + An image can be included in a documentation comment by + surrounding it in double angle brackets: + <<...>>. If the output format supports + it, the image will be rendered inside the documentation. + + Title text can be included using an optional label: + +<<pathtoimage.png title>> + +
@@ -1869,6 +2012,45 @@ module A where the anchor label. The module does not have to be local, it can be imported via an interface.
+ +
+ 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 __bold__ +-- 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 + + +
+ -- cgit v1.2.3