haskell - 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

存在包含仅文档模块的包。 pipes和 generic-random例如。

关于按部分组织事物的两个相关黑线鳕特性是 named chunks和 markup for headings这与 * 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)。