Haddock 模块字段可移植性、稳定性和维护者如何使用？
在许多 Haddock 生成的模块文档中（例如 Prelude），可以看到右上角有一个小框，包含可移植性、稳定性和维护者信息：
通过查看此类模块的源代码和实验，我确认这些信息是由模块描述中类似以下行生成的：
-- Maintainer : [email protected]
-- Stability : stable
-- Portability : portable
关于此有几个奇怪的事情：
这些字段仅似乎按此顺序工作 - 任何不按顺序排列的字段都被简单地视为模块描述本身的一部分。尽管事实上源文件中的顺序与生成的文档中的顺序相反！
我一直无法找到这些字段的任何官方文档。有一个 Cabal 包属性，名为
stability，其示例值与我在等效 Haddock 字段中看到的值相匹配，但除此之外，我什么也没找到。
那么：如何使用这些字段，它们是否在任何地方记录？
特别是，我想知道：
可移植性的常用值的完整列表和稳定性。 此 HaskellWiki 页面 有一个列表，但我想知道该列表的来源.决定模块是可移植还是不可移植的标准。特别是，我想要这些问题的答案，acme-strfry，是一个与
strfry绑定的 FFI，该函数仅在 glibc 中可用。该软件包是不可移植的，因为它仅适用于 glibc 系统，还是可移植的，因为它不使用任何 Haskell 语言扩展？常见用法似乎暗示着后者。为什么源文件中需要特定的字段顺序，以及为什么它与生成的文档中的顺序相反。
In lots of Haddock-generated module documentation (e.g. Prelude), a small box in the top-right can be seen, containing portability, stability and maintainer information:
From looking at the source code to such modules and experimentation, I confirmed that this information is generated from lines like the following in the module description:
-- Maintainer : [email protected]
-- Stability : stable
-- Portability : portable
There are several strange things about this:
The fields only seem to work in this order — any fields put out of order are simply treat as part of the module description itself. This is despite the fact that the order in the source file is the opposite of the order in the generated documentation!
I have been unable to find any official documentation of these fields. There is a Cabal package property named
stability, the example values of which match the values I've seen in the equivalent Haddock fields, but beyond that, I've found nothing.
So: How are these fields intended to be used, and are they documented anywhere?
In particular, I'd like to know:
The full list of commonly-used values for
PortabilityandStability. This HaskellWiki page has a list, but I'd like to know where this list originated from.The criteria for deciding whether a module is portable or non-portable. In particular, the package I would like the answers to these questions for, acme-strfry, is an FFI binding to
strfry, a function only available in glibc. Is the package non-portable, because it only works on glibc systems, or portable, because it does not use any Haskell language extensions? The common usage seems to imply the latter.Why a specific order of fields is required in the source file, and why it's the opposite of the ordering in the generated documentation.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（2）
哦，我以为这些字段来自 cabal 包描述。 Haddock 的文档中似乎根本没有记录它们。我发现了这个，它并没有真正回答你的问题，但是：
http://trac.haskell .org/haddock/ticket/71
因此，如果它是自由格式的，为什么不直接写“不可移植（取决于 glibc）”呢？我什至看到过“便携式（取决于 ghc）”，这很奇怪。我还想知道在 Foo 添加到 Haskell 2010 后，由于非 Haskell98 扩展 Foo 而导致不可移植的模块会发生什么情况。
请注意，您链接到的 Cabal 文档也说稳定性是自由格式的。当然，即使 haddock 或 cabal 定义了可接受的值，仍然需要维护者主观地选择一个值。
关于具体的顺序，您可能应该在 haddock 邮件列表中询问，或者检查源代码并提交错误。
PS：strfry 对 Haskell 社区做出了无价的贡献，但它应该是纯粹且可移植的，你不觉得吗？
Oh, I thought those fields were from the cabal package description. They don't seem to be documented at all on Haddock's docs. I've found this, which doesn't really answer your question but:
http://trac.haskell.org/haddock/ticket/71
So if it's freeform anyway, why not just write "non-portable (depends on glibc)"? I've seen even "portable (depends on ghc)", which is odd. I also wonder what happens with modules that were non-portable due to non-Haskell98 extension Foo, after Foo was added to Haskell 2010.
Note that the Cabal documenation you link to also says stability is freeform. Of course, even if haddock or cabal were to define what are the acceptable values, it'd still be up to the maintainer to subjectively select one.
About the specific order, you should probably just ask at the haddock mailing list, or check the source and file a bug.
PS: strfry is an invaluable contribution to the Haskell community, but it should be pure and portable, don't you think?
啊，是的，这是黑线鳕最晦涩难懂的特征之一。
据我所知，这只是一次未记录的黑客攻击。没有合理的理由说明为什么字段的顺序应该很重要，但确实如此。格式的具体选择（即，作为模块注释内的特殊形式而不是作为某种单独的块）也不是最好的。我的猜测是，有一天有人想快速添加此功能，所以他们编写了一些最小但功能正常的东西，然后就这样了。 （无需费心记录它。）
就我个人而言，我根本不关心这些字段。这些信息可以从 Cabal 获得，所以我也懒得在 Haddock 中复制它。也许有一天，Cabal 会自动将此信息传递给 Haddock……
Ah yes, one of the more obscure and crufty features of Haddock.
As best as I can tell, it's just an undocumented hack. There's no sane reason why the order of the fields should matter, but it does. The specific choice of formatting (i.e., as a special form inside the module comment rather than as a separate block of some kind) isn't the best either. My guess is that somebody wanted to quickly add this feature one day, so they hacked up something minimal but functioning, and left it at that. (Without bothering to document it.)
Personally, I just don't bother with these fields at all. The information is available from Cabal, so I don't bother duplicating it in Haddock as well. Perhaps some day Cabal will pass this information to Haddock automatically...