是否可以使用 Haddock 拥有仅文档文件？

Question

我正在为 Haskell 模块编写文档，其中包含大量测试和示例。这使我的源文件很长（3000 行）。

我的想法是用我的完整示例和文档（没有函数定义）制作第二个源文件 (*.hs)。但是当我编写文档时，我的标题无法正确显示：

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

但是当我像这样打破我的来源时：

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

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

我的文档文本没有出现（我认为 Haddock 正在等待函数导出）。

是否可以仅以这种方式制作带有文档的 Haskell 源文件？

有没有更好的方法来做到这一点？

Answer 1

存在带有纯文档模块的包。例如管道和通用随机。

关于在部分中组织事物的两个相关的黑线鳕特征是命名块和标题标记，这与* Section语法（令人困惑）不同。

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

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

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

有点奇怪的是= XYZ，* XYZ即使它们都归结为<h1>XYZ</h1>HTML，并且呈现方式不同，但您可以通过坚持一种样式来保持所有内容的统一，无论是module在线上方（带有= XYZ标题）还是下方（带有* XYZ标题）。