3.2. Documenting parts of a declaration

In addition to documenting the whole declaration, in some cases we can also document individual parts of the declaration.

3.2.1. Class methods

Class methods are documented in the same way as top level type signatures, by using either the -- | or -- ^ annotations:

class C a where
   -- | This is the documentation for the 'f' method
   f :: a -> Int
   -- | This is the documentation for the 'g' method
   g :: Int -> a

3.2.2. Constructors and record fields

Constructors are documented like so:

data T a b
  -- | This is the documentation for the 'C1' constructor
  = C1 a b
  -- | This is the documentation for the 'C2' constructor
  | C2 a b

or like this:

data T a b
  = C1 a b  -- ^ This is the documentation for the 'C1' constructor
  | C2 a b  -- ^ This is the documentation for the 'C2' constructor

Record fields are documented using one of these styles:

data R a b =
  C { -- | This is the documentation for the 'a' field
      a :: a,
      -- | This is the documentation for the 'b' field
      b :: b
    }

data R a b =
  C { a :: a  -- ^ This is the documentation for the 'a' field
    , b :: b  -- ^ This is the documentation for the 'b' field
    }

Alternative layout styles are generally accepted by Haddock - for example doc comments can appear before or after the comma in separated lists such as the list of record fields above.

In case that more than one constructor exports a field with the same name, the documentation attached to the first occurence of the field will be used, even if a comment is not present.

data T a = A { someField :: a -- ^ Doc for someField of A
             }
         | B { someField :: a -- ^ Doc for someField of B
             }

In the above example, all occurences of someField in the documentation are going to be documented with Doc for someField of A. Note that Haddock versions 2.14.0 and before would join up documentation of each field and render the result. The reason for this seemingly weird behaviour is the fact that someField is actually the same (partial) function.

3.2.3. Function arguments

Individual arguments to a function may be documented like this:

f  :: Int      -- ^ The 'Int' argument
   -> Float    -- ^ The 'Float' argument
   -> IO ()    -- ^ The return value