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 ?
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).