Is it possible to have a documentation only file with Haddock?

Question

I'm writing a documentation for a Haskell module with great number of tests and examples. This make my source file very long (3000 lines).

My idea is to make a second source file (*.hs) with my full examples and only documentation (no functions definitions). But when I write my documentation, I can't have my headers appear correctly:

module JeanJouX.Numeric.Tests (
    -- | Introduction to my module
    --
    -- * Section 1
    -- ** Sub section 1
    -- doc text
    -- ...
    -- * Section 2
    -- ** Sub section 1
    -- 

But when I break my source like this :

module JeanJouX.Numeric.Tests (
    -- | Introduction to my module
    --

    -- * Section 1
    -- ** Sub section 1
    -- doc text
    -- ...
    -- * Section 2
    -- ** Sub section 1
    -- 

My documentation text doesn't appear (I think Haddock is waiting for a function export).

Is it possible to make a Haskell source file with documentation only this way ?

Is there a better way to do it ?

Answer 1

There exist packages with documentation-only modules. pipes and generic-random for example.

Two relevant haddock features regarding organizing things in sections are named chunks and markup for headings which is (confusingly) different from the * Section syntax.

-- | Package description
--
-- = Introduction
--
-- == Subsection Title
--
-- Text.

module MyModule
  ( -- * Section 1
    -- $qsdf
  ) where

-- $qsdf
-- More text.
--
-- == SubSection Title
--
-- etc.

It is a bit weird that = XYZ and * XYZ render differently even though they otherwise both boil down to <h1>XYZ</h1> in HTML, but you can keep everything uniform by sticking to one style, either above the module line (with = XYZ titles) or below (with * XYZ titles).