Haskell Documentation Guide — Haddock Comments and Documentation Generation

In this tutorial, you will learn about Haskell Documentation Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

Haskell Haddock parses documentation comments (-- | for preceding, -- ^ for following) and generates HTML documentation -- supporting module descriptions, type signatures, examples in @ blocks, and cross-references with /'name/ syntax.

Function Documentation

-- | Calculate the area of a circle given its radius.
-- Uses the formula @area = pi * r^2@.
--
-- >>> area 5.0
-- 78.53981633974483
area :: Double -> Double
area r = pi * r ^ 2

-- | Safe division returning Nothing on zero divisor.
-- Returns /Nothing/ when the divisor is zero.
safeDiv :: Int -> Int -> Maybe Int
safeDiv _ 0 = Nothing
safeDiv x y = Just (x `div` y)

Module Documentation

-- |
-- Module    : Geometry.Shapes
-- Copyright : (c) DodaTech 2026
-- License   : MIT
--
-- Maintainer: tutorials@dodatech.com
-- Stability : experimental
-- Portability: portable
--
-- Basic geometric shape calculations.
--
-- This module provides functions for computing
-- area and circumference of common shapes.
module Geometry.Shapes where

Record Documentation

-- | A person with contact information.
data Person = Person
    { personName  :: String  -- ^ Full name
    , personAge   :: Int     -- ^ Age in years
    , personEmail :: String  -- ^ Email address
    , personPhone :: String  -- ^ Phone number
    }

Generating Docs

# Generate HTML documentation
haddock -o docs/ Main.hs

# With hyperlinked source
haddock --hyperlinked-source -o docs/ Main.hs

# Generate for package
cabal haddock
stack haddock

# Hoogle database
stack hoogle -- generate

Common Mistakes

1. Placing doc comments on the wrong side

Use -- | before the definition and -- ^ after the definition (for fields/constructors).

2. Missing module header

Every public module should have a module-level doc comment describing its purpose.

3. Not including examples

Haddock supports >>> for doctest-style examples that also serve as tests.

Practice Questions

1. How do you document a function in Haddock? Place -- | Description before the function definition. Use @code@ for inline code.

2. How do you generate Haddock documentation? cabal haddock or stack haddock generates HTML documentation in the standard output directory.

3. What does >>> do in Haddock comments? Marks a doctest example. The output after the code line is the expected result.

FAQ

{{< faq question="Can I include images in Haddock?" >}} Yes, use <<file.png>> to include images. The file path is relative to the source file. {{< /faq >}}

{{< faq question="What is the /value/ syntax in Haddock?" >}} It creates a hyperlink to the named value. 'Data.List.sort' links to the sort function. {{< /faq >}}

{{< faq question="Can I write multi-paragraph docs?" >}} Yes. Separate paragraphs with blank lines. Haddock preserves the paragraph structure in HTML output. {{< /faq >}}

What's Next

Now learn about the Stack build tool.