How to Write Haddock Documentation People Actually Use
Your Haskell library compiles, the tests pass, and the Hackage page still looks like a wall of bare type signatures that nobody can learn from.

Your Haskell library compiles, the tests pass, and the Hackage page still looks like a wall of bare type signatures that nobody can learn from. Good Haddock documentation is usually the difference between a package people adopt and one they open, squint at, and close. This guide covers how I write Haddock documentation for open source libraries I maintain, what the markup actually does, and the habits that keep docs accurate after the tenth release.
What Haddock documentation actually reads
Haddock does not read every comment in your module. It only picks up line comments where the usual two dashes are followed by a special marker character, and it attaches each one to the declaration next to it. There are two markers you will use 90 percent of the time:
- The pipe marker (two dashes, a space, then a vertical bar) goes before a declaration and documents whatever follows it: a function, a type, a class, a module header.
- The caret marker (two dashes, a space, then a caret) goes after something and documents what came just before. This is the one you want for record fields, constructor arguments, and individual function parameters.
The export list matters as much as the comments. Haddock lays out the module page in the order of your export list, and a comment line with an asterisk marker, such as "* Running queries", inside that list becomes a section heading on the rendered page. If your module has no export list, you get every top level binding in source order, which is rarely the order a newcomer should read them in.
The markup worth learning first
Haddock markup is small. You can learn the useful part in an afternoon, and it covers nearly everything a library page needs.
| You write | Haddock renders | Use it for |
|---|---|---|
| 'runQuery' | a link to that identifier | pointing at related functions |
| "Data.Pool.Lite" | a link to that module | cross referencing modules |
| @withPool cfg action@ | inline monospace | short code fragments in prose |
| a line starting with >>> | an example block | runnable examples |
| @since 0.4.0 | a "Since" note | when an API appeared |
| a dollar marker such as $usage plus a matching chunk | a named prose section | longer tutorials inside a module |
The single most valuable item in that table is the example block. A line that begins with three greater-than signs, followed by the expected output on the next line, renders as a highlighted example. Better still, tools such as doctest and cabal-docspec can run those lines and fail your build when the output drifts.
The @since annotation is the second most valuable. When someone pins your package to version 0.3 and wonders why a function is missing, @since 0.4.0 answers the question in one glance. If you already follow the Haskell PVP versioning rules for maintainers, adding @since to every new export costs you ten seconds per release.
A structure for module pages that people finish
Most readers arrive at your top module from a search result or a dependency list. They want to know three things fast: what the package does, how to make it do one thing, and where to look next. I write every main module page in this order:
- One paragraph of purpose. What problem it solves and for whom. Two or three sentences, no history lesson.
- A minimal working example. Imports included, under 15 lines, copy and paste ready. If it needs a running Postgres server, say so on the first line.
- Sections in the export list. Group functions by task, such as creating, querying, and cleaning up, not by type or alphabetically.
- Per function docs with one example each for anything that takes more than two arguments or can throw.
- A pointer to further modules using module links, so the reader never has to guess which import holds the advanced API.
For each function, the comment should answer what it returns, when it fails, and what it costs if that is not obvious. "Blocks until a connection is free, up to the configured timeout, then throws PoolTimeout" is worth more than three paragraphs about design philosophy.
Why I stopped relying on the README
The common advice is to put your getting started guide in the README and keep Haddock terse. I followed that for years, and I now think it is backwards for most Haskell libraries.
The reason is simple: the README is not versioned with your API the way Haddock is. Hackage shows module docs for the exact version a user has installed, while the README on the package page and the repository front page usually reflect whatever is on the main branch. When you rename a function in 2.0, the README example silently breaks for everyone still on 1.x, and no compiler or doctest run warns you.
So my rule is: the README gets a two sentence pitch, the install line, and a link to the main module. The real tutorial lives in a named Haddock chunk inside the top module, with tested examples. It sits next to the code it describes, it changes in the same pull request, and it is always correct for the version on screen.
Building and publishing Haddock documentation on Hackage
Hackage tries to build docs for every upload, but its builder can fail on packages with system dependencies, unusual flags, or a busy queue. The result is a package page with "docs pending" or no docs at all for days. You can skip that wait by building and uploading the docs yourself.
- Run cabal haddock with the haddock-for-hackage flag in the package directory. It produces a tarball in your dist-newstyle folder with the right link layout for Hackage.
- Upload your package as normal with cabal upload, ideally as a candidate first. The steps in publishing a Haskell package on Hackage the right way cover candidates in detail.
- Run cabal upload with the documentation flag and the docs tarball, adding the publish flag once you have checked the candidate page.
Locally, cabal haddock with the open flag shows you the rendered output in a browser in a few seconds. I click through it before every release; it has caught broken links and a whole module I forgot to export.
In CI, add a step that runs haddock and fails on warnings about missing documentation for exported items. Haddock prints a coverage percentage for each module; I aim for 100 percent on public modules and do not care about internal ones.
Keeping docs honest over many releases
Docs drift when they live far from the change that broke them. Three habits keep mine close to the truth:
- Tested examples. Run doctest or cabal-docspec in CI, so a changed output fails the build like any other test.
- Doc review in every pull request. If a contributor changes behavior, the review checklist asks whether the comment above that function still says the right thing. New contributors often find this the easiest way to help, which is worth mentioning in your guide for a first open source contribution to a Haskell project.
- Deprecation pragmas with directions. A DEPRECATED pragma shows up in Haddock and in compiler warnings. Always say what to use instead and in which version the old name goes away.
Frequently asked questions
How do I document function arguments in Haddock?
Put each argument on its own line in the type signature and add a caret marker comment after it. Haddock renders those as a table of arguments under the function. It works for record fields and constructor fields in the same way.
Why does my package show no documentation on Hackage?
Usually the Hackage doc builder failed or has not reached your package yet, often because of a missing system library or a dependency that would not build. Check the build report link on the package page. If it failed, build the docs locally with the haddock-for-hackage flag and upload them with the documentation flag of cabal upload.
Can Haddock examples be tested automatically?
Yes. Examples written with the three greater-than prompt can be run by doctest or cabal-docspec, which compare the real output to the expected line beneath. Add one of them to CI and broken examples fail the build before a release goes out.
More in Open Source
Open Source
How to Review a Pull Request on a Haskell Project
A contributor sent a 38 line patch to a logging package I help maintain.
Open Source
How to Deprecate a Haskell Package Without Breaking Users
I retired a small Haskell package in 2023 and did it in exactly the wrong order.
Open Source
How to Vet a Haskell Dependency Before You Add It
A student in my second year class added a JSON library to her project because it was the first result she found and the README...