Haskell пикша автоматическая документация

Question

Я не смог сгенерировать документацию для haskell, используя пикшу.

Пока я не нашел никаких полезных примеров. В документации много опций, а также я не уверен в синтаксисе комментариев, чтобы документация генерировалась правильно.

Я знаю, что внутри ghci я могу вызвать: bro для загруженных файлов, и он перечисляет типы и функции, я хотел бы, чтобы эти функции могли быть задокументированы с помощью пикши даже без комментариев. Я не знаю, возможно ли это.

Answer 1

Если вы создаете исполняемый файл, как

module Main (main) -- this line is implicit if your module isn't named otherwise
   where

-- | Some important function that does most of the work
foo :: Bar -> Baz
foo = ...

-- Other definitions
-- ...

-- | The program you want to run.
main :: IO ()
main = ...

-- ...

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

Сформировать также документацию для fooнужно экспортировать, либо напрямую из Main модуль или из другого модуля, где он изначально определен. Обычный способ - поместить все действительно интересное в некоторые "внутренние" модули, например

module Foo (foo, {- other stuff ... -}) where

-- | Some important function that does most of the work
foo :: Bar -> Baz
foo = ...

-- Other definitions
-- ... but not `main`

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

module Main (main) where

import Foo

main :: IO ()
main = ...

Тогда документация для Foo будет содержать действительно интересные Haddocks API Haskell. Это будет выглядеть как

Foo

foo:: Bar -> Baz
Некоторая важная функция, которая делает большую часть работы

На самом деле, вы хотите написать документацию что-то вроде

-- | Transmogrify a bare bar into a zapcutted one
foo :: Bar -- ^ The bare input to transmogrify
    -> Baz -- ^ The zapcutted wrimch

документация выглядит как

Foo

foo::

• Bar Голый вход для трансмогрификации

• -> Baz Отрезанный брус

Преобразуйте голый слиток в срезанный

Пикша для Main не очень интересно, вы могли бы лучше поместить информацию в какое-то окно справки командной строки.

в project.cabal файл, то вам нужно классифицировать Foo как принадлежность к "библиотечной" части проекта, тогда как Main это исполняемая часть.

По сути, Haddock предназначен только для библиотек, а не для исполняемых файлов.