Skip to content
FileFlip

Haddock File Format (.haddock)

A Haddock file holds documentation written in Haddock markup, the comment syntax Haskell's own documentation generator reads out of source files to build a module's API reference.

.haddockDocuments

Haddock at a glance#

Full nameHaddock markup
File extension.haddock
CategoryDocuments
DeveloperSimon Marlow
First released2002
CompressionUncompressed
SpecificationHaddock User Guide
FileFlip supportFileFlip reads and writes this format

What a .haddock file can hold#

These are the things a Haddock file either supports or does not, and they are what decides whether a conversion keeps everything or quietly drops something.

Selectable textYes
Human readableYes

Strengths and limitations of Haddock#

What Haddock does well

  • Doc comments (-- | before a declaration, -- ^ after one) live directly next to the code they describe, so documentation and implementation stay in the same file
  • Links to another function, type or module are checked against the real identifier, so a rename doesn't leave a dead reference behind
  • Ships with GHC and Cabal, so every Haskell package already has the tooling to build docs from it

Where Haddock falls short

  • Markup is minimal by design: emphasis, code blocks and identifier links cover most of what it can do, with nothing like a table
  • Only means something inside a Haskell source file; there's no standalone document most people write directly in it
  • Rendering depends on Haddock parsing the surrounding Haskell syntax correctly, so a doc comment placed oddly can fail silently

Write Haddock markup directly in Haskell source comments so `cabal haddock` can generate the package's API documentation.

Convert Haddock markup to Markdown when the same text needs to appear in a README or a project website outside the generated API docs.

How to open a .haddock file#

A .haddock file opens in the programs below, grouped by the platform you are on. If you would rather not install anything, FileFlip converts Haddock into a format your machine already opens, and it does it in the browser tab rather than on a server.

PlatformPrograms that open it
WindowsAny text editor
macOSAny text editor
LinuxAny text editor
WebHackage, FileFlip

Haddock questions people ask#

What is a .haddock file?

A .haddock file holds text written in Haddock markup, the comment syntax Haskell's documentation generator reads. In practice this markup normally lives inside `-- |` and `-- ^` comments in a .hs source file rather than a standalone file, so a .haddock file usually appears when that text has been extracted or converted on its own.

How do I generate documentation from Haddock comments?

Running `cabal haddock` or `stack haddock` in a Haskell project reads the Haddock comments in its source files and builds an HTML API reference, the same kind of page Hackage hosts for every published package.

What's the difference between -- | and -- ^ in Haddock?

-- | attaches a Haddock doc comment to the declaration that follows it, while -- ^ attaches one to the declaration or argument just before it. The choice is about position: -- | documents forward, -- ^ documents backward.

Converting Haddock files#

Convert Haddock to another format

See every Haddock conversion (37 more)

Convert another format to Haddock

See every document conversion (62 more)

Every conversion runs inside your browser. The file is read from your disk, the work happens on your own machine, and nothing is uploaded. How FileFlip works names the engine behind each family and how to verify that for yourself.