Возможно ли иметь файл документации только с пикшой?

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

Текст моей документации не отображается появляются (я думаю, что Хэддок ждет экспорта функции).

Возможно ли сделать исходный файл Haskell с документацией только таким образом?

Есть ли лучший способ сделать это?

Answer 1

Существуют пакеты с модулями только для документации. Например, pipe и generi c -random .

Две важные функции пикок, относящиеся к организации вещей в разделах: именованные чанки и разметка для заголовков , которая (смешанно) отличается от синтаксиса * 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).