haskell / haddock

Haskell Documentation Tool

Haddock

Haddock is the standard tool for generating documentation from Haskell code. Full documentation about Haddock itself can be found in the doc/ subdirectory, in reStructuredText format.

Project overview

This project consists of three packages:

• haddock: provides the haddock executable. It is implemented as a tiny wrapper around haddock-api's Documentation.Haddock.haddock function.

• haddock-api: contains the program logic of the haddock tool. The haddocks for the Documentation.Haddock module offer a good overview of the functionality.

• haddock-library: is concerned with the parsing and processing of the Haddock markup language. Unlike the other packages, it is expected to build on a fairly wide range of GHC versions.

Contributing

See CONTRIBUTING.md to see how to make contributions to the project.

haddock's Issues

Optionally show qualifications of identifiers

Original reporter: anonymous

Optionally show qualifications of identifiers, that is print "Sequence.map" rather than "map", "Music.T" rather than just "T". The option for haddock could be

    --qualification QUAL
          QUAL=none   (default) strip off qualification (just "map")
          QUAL=orig   show the identifiers as they are written in the module (e.g. "map" or "List.map")
          QUAL=full   show all identifiers with full qualification (Data.List.map)

Actually I tried to implement it by myself in the old Haddock, but I could not precisely identify the place, where the qualification is removed.

Print a warning message when given -optghc instead of --optghc

Original reporter: david.waern@

Since the flag --optghc is so similar to GHC's -optghc, and -optghc is interpreted as the -o flag with an argument (making Haddock silently accept it), it would good to give a warning message in this particular case to avoid mistakes.

Type signatures lose parentheses

Original reporter: anonymous

Under certain circumstances syntactically necessary parentheses are dropped from type signatures. Both of these examples are real code, though simpler examples could be found.

• Case 1: Strict multi-token fields

data (f :+: g) e = Inl !(f e) | Inr !(g e)

• Case 2: Per-argument comments on function arguments.

pairWithBy :: (a -> b -> c) -- ^ @(,)@ tuple homomorphism
-> (c -> d -> d) -- ^ @(:)@ list homomorphism, pt. 1
-> d -- ^ @[]@ list homomorphism, pt. 2
-> [a] -> [b] -> Maybe d -- a safer @zip@ function

Incorrect warnings for SOURCE pragmas

Original reporter: nad

Consider the following files:

A.hs-boot:

module A where

x :: a

A.hs:

module A where

import B

x = y

B.hs:

module B where

import {-# SOURCE #-} A

y = x

The SOURCE pragma is clearly necessary (GHC 6.8.3 does not warn about it), but Haddock (both 2.1.0 and the most recent darcs version) gives a warning:

$ haddock A.hs B.hs

B.hs:3:0:
    Warning: Unnecessary {-# SOURCE #-} in the import of module `A'

This is quite annoying, since our project relies on -Wall -Werror, cabal haddock reuses the GHC options from the Cabal file, and there is no flag for turning off just the given warning.

This may be related to http://hackage.haskell.org/trac/ghc/ticket/1833, by the way.

The docs should mention the module header

Original reporter: david.waern@

Non-recognised declarations can "get in the way" of Haddock comments being recognised

Original reporter: david.waern@

Pragmas and other non-recognised declarations can stop Haddock commentation being recognised.

e.g. This is undocumented in the resulting haddock ("A comment" is
missing).

-- | A comment.
{-# INLINE genVennAsList #-}
genVennAsList :: (a -> b -> COrdering c) -> AVL a -> AVL b -> (AVL a, [c], AVL b)
genVennAsList cmp = genVennToList cmp []

.. but this is OK

-- | A comment.
genVennAsList :: (a -> b -> COrdering c) -> AVL a -> AVL b -> (AVL a, [c], AVL b)
{-# INLINE genVennAsList #-}
genVennAsList cmp = genVennToList cmp []

Include file revision info in module headers

Original reporter: david.waern@

Parsing module without explicit module declaration fails

Original reporter: sol@

If a module does not contain an explicit module declaration
and starts with

-- | some comment

then parsing fails.

This is a bug in GHC's parser. It is only triggered if
Opt_Haddock is used.

Details

GHC's parser has a rule for Haddock comments on module headers.
When the parser sees the Haddock comment at the
beginning it then wants the next declaration to be a module header
(the grammar has an S/R conflict because of this).

One possible solution could be to parse Haddock comments separately from the Haskell code, and match up Haddock comments with AST nodes in a later step.

Steps to reproduce

-- | Hi there
main = print "Hello World!"

Running

$ haddock Main.hs

fails with:

Main.hs:2:1: parse error on input `main'

In contrast both of the following example work just fine:

{-
Hi there
-}
main = print "Hello World!"

foo = 23
-- | Hi there
main = print "Hello World!"

Haddock build failure under GHC-6.8.3

Original reporter: oddron@

Haddock 2.1.0 fails to build under ghc-6.8.3.
Here is the error I'm getting:

[15 of 24] Compiling Haddock.GHC.Typecheck (
src/Haddock/GHC/Typecheck.hs,
dist/build/haddock/haddock-tmp/Haddock/GHC/Typecheck.o )

src/Haddock/GHC/Typecheck.hs:82:4:
Constructor HsModule' should have 7 arguments, but has been given 8 In the pattern: HsModule _ _ _ _ _ mbOpts _ _ In a pattern binding: HsModule _ _ _ _ _ mbOpts _ _ = unLoc parsed In the definition ofmkGhcModule':
mkGhcModule (mod, file, checkedMod) dynflags
= GhcModule
{ghcModule # mod, ghcFilenamefile,
ghcMbDocOpts = mbOpts,
ghcHaddockModInfo # info, ghcMbDocmbDoc,
ghcGroup = group,
ghcMbExports = mbExports,
ghcExportedNames = modInfoExports modInfo,
ghcNamesInScope = fromJust $
modInfoTopLevelScope modInfo,
ghcInstances = modInfoInstances modInfo}
where
HsModule _ _ _ _ _ mbOpts _ _ = unLoc parsed
(group, _, mbExports, mbDoc, info) = renamed
(parsed, renamed, _, modInfo) = checkedMod

Nested itemized and enumerated lists

Original reporter: david.waern@

Nested itemized and enumerated lists.

Comments on default method declarations

Original reporter: david.waern@

suggested by Satnam.

The Haddock comment lexer should handle "...." in doc strings

Original reporter: anonymous

The lexer should handle "...." in doc strings, only recognising it if the contents looks like a module name.

Support structure (section headings, etc) in the description and possibly in other comments

Original reporter: david.waern@

There ought to be a way to include some structure in the "description" (section headings, etc.) and possibly in other comments. (suggested by Daan).

Something equivalent to JavaDoc's @since

Original reporter: david.waern@

Something equivalent to JavaDoc's @since.

Documentation of arguments of type constructors other than 'top level' arrows

Original reporter: david.waern@

Documentation of arguments of type constructors other than 'top level' arrows. E.g.

   T (a {- ^ arg -}  ->  b {- ^ result -} )
   (a {- ^ arg -}  ->  b {- ^ result -} ) -> c
   (a {- ^ x coord -}, b {- ^ y coord -}) -> c

It's probably difficult to format properly in HTML.

Do something better about re-exported symbols from another package

Original reporter: david.waern@

Do something better about re-exported symbols from another package.

Top-level Haddock comments must follow the layout of declarations

Original reporter: david.waern@

If layout is used, a Haddock comment must be at the same indentation level as the declaration it is commenting. As an example, the following causes a parse error:

  -- | doc comment for f
f :: Int
f = 1

This needs to be fixed in the GHC lexer, hence the 2.3.0 milestone.

Hide instances that are "internal" to a module

Original reporter: david.waern@

Add some way to refer explicitly to either a type/class constructor or a data constructor

Original reporter: david.waern@

There's no way to refer explicitly to either a type/class constructor or data constructor when there are more than one of these with the same name. Perhaps introduce a special syntax for them? (eg. ':C' means data constructor C?)

Haddock barfs if used to build GHC

Original reporter: bos@

When I tried to build a GHC 6.8.3 snapshot using Haddock 2.0.0.0, it refused, complaining that the internal version of GHC was different from the internal version of Haddock. Clearly, this is a rather huge problem if one wants to upgrade.

Remove extra whitespace from the generated HTML to save space

Original reporter: david.waern@

Show fixities in the documentation

Original reporter: david.waern@

A module re-export should only reference the target module if all of it is imported

Original reporter: david.waern@

A module re-export should only reference the target module if the target module is imported without hiding any of its exports (otherwise we should inline just the exported bits).

For a constructor, don't fill its entire cell with a grey background.

Original reporter: david.waern@

Allow more parts of the documentation to be squashed and expanded

Original reporter: david.waern@

The user should not have to provide the path to GHC

Original reporter: david.waern@

We should find a way to get the path to the GHC lib dir automatically, without the user having to specify it. The user should still be able to override this path, of course.

In the contents page, indicate portability/stability of each module somehow

Original reporter: david.waern@

Modules without docs don't need both a synopsis and a documentation section

Original reporter: dwaern

The synopsis generated for a module with no docs should not attempt to link to the doc for each entity. We need a different kind of summary here: what we really want is just the documentation section but without the extra whitespace between decls.

There should be a --maintainer flag

Original reporter: david.waern@

There should be a --maintainer flag to allow Cabal to pass the maintainer from the .cabal file to the generated docs.

Comments on GADT constructors

Original reporter: jeanphilippe.bernardy@

eg. this fails:

data I ev w a where
Returns :: a -> I ev w a
Binds :: I ev w a -> (a -> I ev w b) -> I ev w b
Gets :: Ord ev => Maybe ev -> Maybe ev -> I ev w ev
-- ^ Accept any character between given bounds. Bound is ignored if @nothing@.

Opera doesn't like url-encoding in <a name>

Original reporter: claus

It seems that relative Urls like

file:///C:/ghc/ghc-6.9.20080514/doc/libraries/base/Data-List.html#v%3Ahead

don't work with Opera (9.51, windows). Or, rather, the urls do work if the corresponding 'name' is not url-encoded but not if it is. I don't know whether that is an Opera issue - for Internet Explorer, the situation seems reversed (the url works if the 'name' is url-encoded but not if it isn't).

I'm surprised by this incompatibility, but haven't yet found any relevant info.
If there is no other workaround, haddock could perhaps generate both encoded and un-encoded names?

Indicate changed between versions in the documentation

Original reporter: david.waern@

Haddock could compare interfaces from multiple versions of a module and indicate changes between versions (eg. a small "new!" or "changed!" icon, or "stable since 1.0").

Haddock comments needs to be separated by semi-colons when explicit layout is used

Original reporter: anonymous

Haddock comments are parsed as separate declarations so we need to insert a ';' when using them with explicit layout:

module NoLayout where {
  -- | the class 'C'
  ;
  g :: Int;
  g = undefined
 }

This should be fixed in the GHC parser, hence the 2.3.0 milestone.

Links with to page anchors don't work in Opera 9.5x

Original reporter: larsko

The anchors Haddock generates to e.g. link to function documentation from the synopsis contain a percent-escaped colon after the #. Opera apparently unescapes it and then tries to find the anchor with the colon (e.g. "foo.html#v%3Afoobar" becomes "foo.html#v:foobar"). The anchor definition also uses the %-escaped colon though and is therefore not found.

A possible solution to this problem is to escape the percent sign in the link, i.e. have "foo.html#v%253Afoobar" in the link and "foo.html#v%3Afoobar" in the anchor definition. On the other hand it would probably be cleaner to only use characters which do not need to be escaped in the generated links.

ghc-paths won't build (hence Haddock 2.2.0 won't either

Original reporter: wren ng thornton

I'm not sure if there's any better place to log this ticket but...
Configure fails when trying to install ghc-paths version 0.1.0.2:

Setup.hs:7:7:
Could not find moduleDistribution.Simple.PackageIndex': Use -v to see a list of the files searched for. * Exited with value 1`

internal Haddock or GHC error on some packages

Original reporter: ross@

The following packages cause Haddock to fail reporting internal errors:

• mtl-tf-0.1
  haskell haddock: internal Haddock or GHC error: src/Haddock/Interface/Rename.hs:(297,16)-(326,1): Non-exhaustive patterns in case
• sessions-2008.5.12
  haskell haddock: internal Haddock or GHC error: src/Haddock/Interface/AttachInstances.hs:(125,0)-(126,47): Non-exhaustive patterns in function toHsPred
• uvector-0.1
  haskell haddock: internal Haddock or GHC error: src/Haddock/Interface/Rename.hs:(297,16)-(326,1): Non-exhaustive patterns in case
  The last one may be something different from the former two.

It may be that the packages are doing something wrong, but the internal error is alarming.

Comments on components of a tuple, for argument or return types.

Original reporter: david.waern@

Parser doesn't support doc comments on type aliases

Original reporter: david.waern@

Parser doesn't support doc comments on types in type aliases:

type MyInt = Int -- ^ comment

This was forgotten during the SoC project, and needs to be fixed in GHC's parser, hence the 2.3.0 milestone.

Add a link to the documentation home of a re-exported entity

Original reporter: david.waern@

For a non-home occurrence of an entity, we should point to the home location in the doc somehow. This would help to distinguish multiple functions with the same name (eg. we don't know whether Prelude.catch is Control.Exception.catch vs. System.IO.Error.catch).

We don't handle non-ASCII characters in doc comments

Original reporter: david.waern@

We don't handle non-ASCII characters in doc comments. (need to specify the encoding in the generated HTML too?).

Mentioning a qualified identifer in doc loses the qualifier

Original reporter: david.waern@

Mentioning a qualified identifer in doc loses the qualifier, even when it is required? (see "[Haskell] auto-qualification of identifiers in Haddock").

The docs should mention the module header

Original reporter: david.waern@

The docs should mention the module header stuff.

Allow documentation annotations to explicitly name the entity they refer to

Original reporter: david.waern@

haddock doesn't support standalone deriving?

Original reporter: claus

also, I'd like to be able to build haddock 2 with ghc head.

Module references in doc strings are always assumed to be in the current package

Original reporter: david.waern@

We don't point module references ("..." in doc strings) to the correct package, they are always assumed to be modules in the current package.

Add back-references from the definition to the uses of types/classes

Original reporter: david.waern@

Add back-references from the definition to the uses of types/classes (perhaps in the index?).

Comments on instance declarations

Original reporter: david.waern@

More and more people really want this.

Perhaps switch to longer rendering form for datatypes when necessary

Original reporter: david.waern@

Add a way to indicate DEPRECATED functions/types/modules

Original reporter: david.waern@

Add a way to indicate DEPRECATED functions/types/modules? Perhaps use the GHC DEPRECATED pragma?

feature request: record types with partially exported fields

Original reporter: avatar@

attached (M1) is an example of a situation, where haddock hides all fields of a record, just because one field is hidden. The result is that the other field is not shown in the documentation as well, even though it is exported.

As an example for why hiding certain fields of a record might make sense, consider M2. There we export two functions for decomposing T: f and g, whereas f is a class function that can be used for other datatypes as well, and g is a function specific to T. The ugly fT function is hidden from the user.

I'd wish myself a haddock output in which T would be shown in record style, but there would be a blank instead of fT or maybe something like "".