New Haddock released! A visual guide to changes.

Posted on March 24, 2014
by Fūzetsu

We’ve just uploaded Haddock 2.14.1 and while you can view the CHANGES file, here I’ll attempt to present all new features added since 2.13.2.1. A quick note that while 2.14.0 is in the CHANGES file, it was never officially released to the public. Consider it an internal release if you will. This basically covers 2.14.0 and 2.14.1. I am posting this now as I hear GHC 7.8.1 is supposed to come out in a few hours and this is the version that you’ll be getting. I had only just realised this but this integrates the changes I have made over the last GSoC into a stable GHC release. FYI, I’m using GHC 7.8-rc2 for any code snippets presented here. Last thing to mention is that any ticket numbers you see here are the tickets as seen on Haddock Trac. We’re actually planning to move everything to GitHub soon so keep that in mind if you’re reading this further in the future. Note that pretty much everything here is described in Haddock documentation (although without nice examples) so please refer to that if you need further information.

Let’s begin!

Print entities with missing documentation (#258)

This adds a --print-missing-docs flag to Haddock. Given a file like this:

There has been a suggestion to make this flag default. I’m personally not against it. What do you think?

Print a warning message when given -optghc instead of --optghc (#5)

This is just a quick fix to a long-standing feature request. The problem was that -optghc actually means --odir=ptghc which is probably not what you wanted. We now warn when we see -optghc in the flags. The warning is:

Warning: `-optghc' means `-o ptghc', did you mean `--optghc'?

Add --compatible-interface-versions (#231)

This simply prints the versions of the .haddock interface files that your Haddock binary knows how to work with.

$ haddock --compatible-interface-versions
25

We had some fairly big changes to the interface file so current Haddock can only work with a single version: this means it can’t re-use .haddock files that your previous versions might have generated.

Allow to generate latex documentation for FFI declarations (#247)

Fairly self-explanatory. Note that I don’t encourage actually trying to use the LaTeX back-end, it is not maintained and has many bugs. It is meant to serve a sole purpose of generating the Haskell Report when that time comes. If you are interested in using this back-end and are willing to put in some time to breathe some life into it, we’d love to have you, contact us!

Add copyright and license information to generated documentation

We let you document modules with a comment containing some special fields. The header is documented here. Consider the following module:

This is by design. We feel that extra complexity of implementation and the fact that it changes how 2.13.2 behaved does not warrant such support. See ticket #126 for minor discussion.

Nested paragraphs

This is a pretty big addition and if you are the type of person that tries to format their comments so that they look nice in source, you’ll probably need to pay attention. Basically, we allow something like what Markdown allows: nesting things under list elements (such as more list elements and so on). A simple example would be nesting some a code snippet and another list under some other list. I’m actually showing off two features here. Consider

{-|* This is some list @ This is code @ * Another list * Second element of inner list, not separated by line break.-}f :: ()
f = ()

2.13.2 makes a mess out of it:

Old nested lists

but 2.14.1 does what you might expect:

New nested lists

The rule is that everything to be nested under a list element is to be indented 4 spaces from the start of the comment. Note that this is not 4 spaces relative from start of the previous list. You also have to make sure that the nested paragraph is separated by a line break so that Haddock doesn’t simply think it’s the continuation of the list.

A double nesting will therefore look like this:

{-|* Top level * First nested * Second nested-}f :: ()
f = ()

Twice nested

Those with sharp eyes will notice that I have two list elements not broken up by the line break in the initial example. This in now allowed as long as the list elements are of the same type:

This is now fine:

-- |-- * foo-- * bar

but this is not fine:

-- |-- * foo-- 1. bar

Haddock will think it’s just a single list element and it will look something like this:

Different type no break

Please refer to list section of the docs for details. These changes mean that you can write much nicer docs but they also mean that if you wrote something that wasn’t exactly model Haddock before, it might now look radically different! I know that even GHC is guilty of this.

Better escaping

We now have much better escaping behaviour. Consider

-- | < http:/haskell.org Haskell.org loves \>\>= >

2.13.2 messes up:

Old link escape

But 2.14.1 works as we’d like it to:

New link escape

It is actually impossible to have the > character in the link or alt text even with HTML escapes because we don’t accept markup there so it won’t get converted.

If you don’t need the alt text, we now even automatically try to convert text to links. Consider

-- | http://haskell.org is coolf :: ()
f = ()

2.13.2 doesn’t do what we want at all and even swallows up the forward slashes because it thinks it sees (empty) emphasis:

Old autolink

2.14.1 does something much more reasonable:

New autolink

You should notice that escaping things is much more reasonable now.

Header markup

Headers in regular comments (rather than just for sections) are now allowed. The syntax is multiple = characters, from 0 up to 6. Each back-end decides how to render the different header levels itself.

Note that headers have to be at the beginning of a paragraph but we do allow a paragraph to follow without a line break right after it. This allows you to write down things like lists and another header straight after.

Parser should no longer fail to parse any markup

We now aim to be able to parse everything. This means that you should never see a parse failure caused by bad Haddock syntax. For example

-- | [ hellof :: ()
f = ()

fails on 2.13.2 with a parse error: doc comment parse failed: [ hello. This will render as you’d expect on 2.14.1:

No parse error

This means that if you had a documentation that failed to parse due to such error before, it will now (silently) succeed.

Important: please note that you can still have a different kind of parse error. If your comment is at a place where we don’t expect it, that’s an error. For example, the following will throw a parse error:

dataF=F () -- ^ Doc for first ()
() -- ^ Doc for second ()

gives us W.hs:18:12: parse error on input ‘(’ because we don’t support documentation of each parameter to the constructors.

Please do not report these as bugs! If you do get a doc comment parse failed then report that, you should not be seeing any of these anymore.

{-# OPTIONS_HADDOCK show-extensions #-} pragma will show the GHC extensions enabled in the module.

This allows HsColour to insert anchors for TH declarations. Nothing to show here, check the ticket for details.

Display fixity information for names with nonstandard fixities

There’s no a mechanism in place to display fixity of (type) operators and infix functions. Includes exotic things like type families and pattern synonyms. Code omitted but there’s nothing special you have to do, your new docs should automagically have fixities shown.

Fixity rendering

Bird tracks specified like “> code” no longer suffer from an extra leading space in the code output

Pretty self explanatory. We strip a leading space from code blocks generated by bird tracks.

-- |-- > hello-- > worldf :: ()
f = ()

Old bird tracks

New bird tracks

This is also planned for the ‘@’ style code blocks which should have this implemented in the next Haddock release, most likely 2.15.0 coming out with GHC 7.8.2.

Render * and -> with their UnicodeSyntax equivalents if -U is enabled

Replaces * and -> in extra places compared to 2.13.2.

Old unicode syntax

New unicode syntax

Display minimal complete definitions for type classes

I feel this is a nice feature. GHC now supports MINIMAL pragmas and we are now able to display it in the docs. Another example right out of the Haddock test-suite:

Again I ask you to ignore the silly ordering of some grouped functions, this is the aforementioned old bug. Hopefully we can fix it by the next release.

Hide right hand side of TF instances with hidden names on the RHS

Changes a bit which TF RHSs are hidden. It is a change between 2.14.0 and 2.14.1 and is only mentioned for completeness.

This is it for all the changes I can think of but I’m sure I missed something! There was some other minor stuff fixed up that doesn’t deserve a mention on its own (such as fixing bullet point rendering in constructor docs, #281) so I encourage you to read the commit history if you need to know all the little details.

While I’d love to end it here, I do have to admit that there’s a regression in this release which we don’t get to fix until GHC 7.8.2.

Namely, if you have a (very common) comment like this:

-- |-- @-- some code-- goes here-- @f :: ()
f = ()

2.13.2 will render it like this:

Old codeblock rendering

and 2.14.1 like this:

New codeblock rendering

The problem is that while Haskellers are used to putting a space after the comment marker --, that space is actually a part of a comment and we end up with an extra ‘empty’ line which actually has a single space in front of it. This is the line with the closing @ on it.

Surprisingly, that second form is allowed. If you care a lot about the extra line, please use a workaround for now and I’m sorry! If you don’t care that it looks a bit on the ugly side for a while, we’ll have a fix in the next release, most likely to ship with GHC 7.8.2.