Some common and annoying mistakes in Haddocks

Slashes mean emphasis, so this:

This is Haskell: (http://en.wikipedia.org/wiki/Haskell)

would be rendered like this:

This is Haskell: (http:/en.wikipedia.orgwiki/Haskell)

Haddock tries to autodetect links, but often fails – so better always wrap them in angle brackets.

Slashes and people who like slashes

For those of us who like using slashes in prose: good/bad/ugly would get rendered as “goodbadugly”, so escape slashes like this: good\/bad\/ugly.

Haddock thinks that all quoted words are links to other modules, so by using "This" in a sentence you might get a link to an unexistent module “This”. Again, escaping helps here. Or using “” quotation marks instead of "" ones. Or simply not taking words starting with a capital letter in quotes.

Code blocks and lambdas

Code blocks (ones surrounded by @s) aren't verbatim. This:

@
map (\a -> a ++ reverse a) xs
@

will produce this:

map (a -> a ++ reverse a) xs

(note the missing slash). The solution once again is escaping.

Code blocks and operators with angle brackets

Even worse, if you dare use <$> in a code block, it will turn into a link to a module called “$”. Either escape angle brackets, or put <$> in single quotes.

Code blocks and emphasis

This one doesn't pop up often, because operators with / in them are pretty rare (there's /=, /, //, but not much else).

@
l //= x = l %= (/x)
@

will produce this (note the emphasis):

l /= x = l %= (x)

Either escape slashes, or put such operators in single quotes.

Code blocks and alignment

Aligning code in code blocks can be tricky. For instance, this nicely aligned code:

view ::             Getter s a     -> s -> a
view :: Monoid m => Fold s m       -> s -> m
view ::             Iso' s a       -> s -> a
view ::             Lens' s a      -> s -> a
view :: Monoid m => Traversal' s m -> s -> m

is produced by this Haddock markup:

'view' ::             'Getter' s a     -> s -> a
'view' :: 'Data.Monoid.Monoid' m => 'Control.Lens.Fold.Fold' s m       -> s -> m
'view' ::             'Control.Lens.Iso.Iso'' s a       -> s -> a
'view' ::             'Lens'' s a      -> s -> a
'view' :: 'Data.Monoid.Monoid' m => 'Control.Lens.Traversal.Traversal'' s m -> s -> m

(Editing such code, naturally, is a pain.) So, check your alignment in browser every time you modify a piece of code in docs.

You can create links to identifiers by wrapping them in single quotes, which works in code blocks and is kinda nice. However, the same thing doesn't work in code examples, so by doing

>>> (1,2) '&' '_1' '%~' 'negate'
(-1,2)

you will get what you see, instead of nicer

>>> (1,2) & _1 %~ negate
(-1,2)

If your editor wraps lines to some width, and a link happens to be wrapped...

...here goes a link: <http://example.com
just an example>. Hope you liked it.

...it won't be recognised as a link. Watch out for wrapped links, I guess.

Read next: Telegram channel