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!

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

Old codeblock rendering

and 2.14.1 like this:

New codeblock rendering

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.

All of the following let you workaround the problem:

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

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

{-|
@
some code
goes here
@
-}
i :: ()
i = ()

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.

Thanks!