Haskell 黑线鳕自动文档

Question

我无法使用黑线鳕为 haskell 生成文档。

到目前为止我还没有找到任何有用的例子。该文档有很多选项，而且我不确定注释语法是否正确生成了文档。

我知道在 ghci 中我可以为加载的文件调用 :bro 并且它列出了类型和函数，我希望即使没有注释也可以用 haddock 记录这些函数。不知道可不可以。

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

-- ...

然后 Haddock 假设没有任何东西 public 可以实际记录 – 毕竟，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 的文档将包含真正有趣的 Haskell API 黑线鳕。这看起来像

Foo

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

实际上，您需要编写类似于

的文档

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

生成的文档看起来像

Foo

foo ::

Bar The bare input to transmogrify

-> Baz The zapcutted wrimch

Transmogrify a bare bar into a zapcutted one

Main 的 Haddock 并不是很有趣，您最好将信息放在一些命令行帮助框中。

在project.cabal文件中，然后需要将Foo分类为属于项目的“库”部分，而Main是可执行部分。

基本上，Haddock 仅适用于库，不适用于可执行文件。

Haskell 黑线鳕自动文档

Haskell haddock automatic documentation

haskell

documentation-generation

haddock

Foo

Foo