问题标签 [haddock]

我想像使用 javadoc 一样格式化我的黑线鳕文档，比如插入 html 或任何其他标记，让我在不排除任何 javascript 或 CSS 的情况下获得更清晰的输出......特别是，我想知道如何插入一行打破文档。

谢谢！

在许多 Haddock 生成的模块文档（例如Prelude）中，可以看到右上角的一个小框，其中包含可移植性、稳定性和维护者信息：

从查看源代码到此类模块和实验，我确认此信息是从模块描述中的以下行生成的：

这有几个奇怪的地方：

• 这些字段似乎只按此顺序工作——任何乱序的字段都被简单地视为模块描述本身的一部分。尽管源文件中的顺序与生成的文档中的顺序相反！

• 我一直无法找到这些领域的任何官方文档。有一个名为的Cabal 包属性stability，其示例值与我在等效的 Haddock 字段中看到的值相匹配，但除此之外，我什么也没找到。

那么：这些字段打算如何使用，它们是否记录在任何地方？

特别是，我想知道：

• Portability和的常用值的完整列表Stability。这个 HaskellWiki 页面有一个列表，但我想知道这个列表的来源。

• 决定模块是可移植还是不可移植的标准。特别是，我想要回答这些问题的包acme-strfry是一个 FFI 绑定，它是一个strfry仅在 glibc 中可用的函数。包是不可移植的，因为它只适用于 glibc 系统，还是可移植的，因为它不使用任何 Haskell 语言扩展？常见的用法似乎暗示后者。

• 为什么源文件中需要特定的字段顺序，以及为什么它与生成的文档中的顺序相反。

我的项目中有一个虚拟模块，其唯一目的是为库的其余部分保存 Haddock 文档。实际上我不需要在这个模块中导入任何东西，但是如果我不导入其他模块，Haddock 不会将函数名称超链接到它们的模块。

我的模块看起来像这样

现在，如果我构建项目，我会收到以下警告：

如果我删除导入或制作它们()，Haddock 不会超链接someFunction到其文档。如果我保留这样的导入，我会收到很多我不喜欢的错误警告。而且我不想在整个项目中抑制这种警告，它可能对除此之外的任何其他模块有用。

问题：

1. 构建时如何在没有此类警告的情况下获得超链接的 Haddock 输出？
2. 是否可以基于每个文件禁用警告？（就像我可以在全球范围内使用ghc-optionsin一样.cabal）

Haddock 似乎错误地重新编码了 UTF-8 编码源文件中文档中的非 ASCII 字符。我经常需要在文档中包含数学公式，如果可以使用一些常见的数学符号，例如求和 (∑)，它们的可读性会更高。

但是，通过黑线鳕运行文件后，这些符号变成空白方块。Haddock 有这个选项--use-unicode，但它只是将函数签名等中的函数箭头转换为 unicode 字符，同时仍然破坏实际文档。

如果这可以控制就更好了cabal haddock！

我正在使用 Haddock 2.9.4 版。

举个例子：

奇怪的是，未导出声明的文档字符串被忽略了，即使我们得到了正确的结构：

有人有线索吗？作为记录，调用 viacabal haddock --internal无济于事，haddock --ignore-all-exports.

有没有办法将 Haddock 文档添加到导出它的模块中的实体，而不是声明它的实体？

我有一个隐藏模块，它声明了十几种类型，然后是另一个模块，它只导出最终用户应该看到的部分。将文档放在公开模块而不是隐藏模块中是合乎逻辑的。但我无法弄清楚如何做到这一点......

假设有一个Foo不受我控制的库模块：

thing现在假设我有自己的库模块，它从模块中重新导出Foo。

出于兼容性原因，我不想导出不同的thing. 我想确保我 export Foo.thing，这样如果用户同时导入Foo和Bar模块，它们将得到相同的结果thing并且不会发生名称冲突。

现在假设我们有第三个模块使用Bar.

让我们将第三个加载到 ghci 中。

而不是 ghci 和黑线鳕表明thing在 moduleBar有 type Foo.Foo，我希望它声明thing有 type Bar。有没有办法在不导出不同的情况下实现这一点thing？

我想开始使用黑线鳕；主要原因不是我（或其他任何人）需要很好的 HTML 文档来编写我现在正在编写的内容，而是它将教会我一种标准化的方式来评论 Haskell 模块。出于这个原因，我想亲自动手，但我遇到了一个非常基本的问题。

资源：

黑线鳕调用：

看起来 Haddock 不知道在哪里寻找标准库，但这只是一个疯狂的猜测。文档对“-B”参数说了一些话，但并没有真正解释太多。

我在网上搜索了这个问题，基本上得到了“使用 Cabal 包，它会为你做所有事情”的回答。但是，我宁愿现在不和Cabal打交道，而是自己学习黑线鳕（Cabal可以等待）。是否有一个很好且简单（ish）的解决方案？

我尝试haddock通过运行以下命令进行安装，cabal install haddock但遇到了以下问题。

有没有人知道如何处理这个烂摊子？

编辑 我的 ghc 版本是 7.4.1

我目前正在Haskell 上开发小型应用程序。我也有所有记录main。但cabal haddock --executables显示错误：

而Main.hs它本身：

为什么haddock找不到文档main？

使用ghc-7.0.4,cabal-1.10.2.0和。haddock-2.9.2_Fedora 17