Пикша комментирует импортированные объекты

Question

Есть ли способ добавить документацию Haddock к сущности в модуле, который ее экспортирует, а не к той, которая ее объявляет?

У меня есть скрытый модуль, который объявляет дюжину типов или около того, а затем другой модуль, который экспортирует только те части, которые должен видеть конечный пользователь. Было бы логично поместить документацию в открытый модуль, а не в скрытый. Но я не могу понять, как это сделать...

Answer 1

Нет, это невозможно. Функции могут иметь документацию по каждому аргументу и параметру, и это сделает документацию непоследовательной, если вы сможете:

1. пишите разные версии в разных местах
2. иметь одну версию переопределить другую
3. внесите несоответствия в документацию аргументов: что если вы переопределите основную строку документа для функции; должны быть удалены аргументы doc?

Следующий файл:

module Bla
       ( -- * Fooishness

         -- | This is 'foo'. It is not 'bar'.
         foo
       , -- * Barishness

         -- | This is 'bar'. It is sometimes a little 'foo'.
         bar
       ) where

-- | The actual foo documentation
foo :: a -- ^ The a
    -> b -- ^ The b
    -> c
foo = undefined

-- | The actual bar documentation
bar :: a
bar = undefined

... выдает эту документацию:

Как видите, комментарии к разделу можно использовать для эмуляции строк документации по функциям, но документация будет генерироваться правильно только в том случае, если вы используете комментарии к документации по функциям непосредственно по сигнатурам типов.

Answer 2

Ну, если подумать, я мог бы написать newtype в выставленном модуле. Он не несет никаких накладных расходов, он просто делает мой код немного более грязным...