如何使用Haddock减少文档重复

Question

我有两个非常相似的函数，它们都需要完全相同的文档。在 Haddock 中有没有避免注释重复的方法？

我在 Haddock 文档中找不到这个功能的描述，但我猜应该有一种方法可以做到。

例如，在 Javadoc 中有 {@inheritDoc} 和 @see SomeClass#someMethod()。Haddock 有什么类似的功能呢？

- klappvisor

---

我认为你可以使用命名的文档块（https://www.haskell.org/haddock/doc/html/ch03s05.html）来实现这一点（我从未尝试过，但有时当我注释掉一个美元符号时，我会看到haddock抱怨，例如“- $ foo”）。您可以为块定义名称，但显然只能在导出列表中使用它，并且必须位于注释开头。 - d8d0d65b3f7cf42

如果这些函数密切相关，最好不要重复文档，而是将读者引用到其他函数的文档。然后，如果它们仅由类型不同，读者将看到一个描述和两个具有略微不同类型签名的函数。 - Cirdec

Answer 1

目前，使用Haddock无法为函数声明提供可重用的文档。这里有一个跟踪此问题的问题。

-- $chunk_name文档块命名仅适用于模块文档，即仅适用于导出部分。这对于将模块顶部的文档移动到底部以减少混乱非常方便。

解决此问题的常见方法包括：

• 确保相似的函数在作用域内，并将其添加到文档中： -- | 参见 `functionName`。 OR -- | 参见 'functionName'。
• 如果文档足够小，则手动复制和粘贴文档，类似于bytestring和vector软件包中的操作。

- lehins

---

是的，似乎唯一引用文档的方法是使用 -- | 参见 '函数名'，我们可以通过这个例子来扩展答案。 - klappvisor