6

In module B I have documentation with a link 'A.foo', linking to the foo member of module A. In module A I import module B. Haddock renders this as a link to A.html#t:foo, namely pointing at the type foo (which does not exist) not the function foo, which is at A.html#v:foo.

  • Why does Haddock link to t: for variables that start with a lower case letter? Is that a bug? For 'A.Foo' I can see that it could be a type or a constructor, so there are namespacing issues. For foo it seems a variable is at least most plausible.
  • Is there any way to fake a link? I am writing this in code samples, so I need it to be rendered as foo. I tried anchors, but they render as the module name, and for direct hyperlinks you have no control over the displayed text.
  • I considered a post processor (replacing t:[a-z] with v:), but that requires a custom Setup.hs which causes problems and is quite ugly.
  • I couldn't find any Haddock command line flags to obtain a more reasonable behavior, such as specifying that foo is a variable.
  • I can't add an import of A to B without introducing circular imports, which is vile to add purely for documentation.

I am running into this problem in the Shake documentation, where as an example removeFilesAfter does not get the right link.

4

2 回答 2

4

我可以部分回答第一个问题（为什么？）；不确定这是错误还是期望的行为。

当 haddock 解析 中的引用时LexParseRn.rename，它会尝试在环境中查找标识符（通过lookupGRE_RdrName）。这应该会失败。接下来它看起来是什么意思（使用dataTcOccs来自 GHC'sRnEnv）。相关线路是：

dataTcOccs :: RdrName -> [RdrName]
-- Return both the given name and the same name promoted to the TcClsName
-- namespace.  This is useful when we aren't sure which we are looking at.
dataTcOccs rdr_name
  [...]
  | isDataOcc occ || isVarOcc occ
  = [rdr_name, rdr_name_tc]
  [...]
  where
    occ = rdrNameOcc rdr_name
    rdr_name_tc = setRdrNameSpace rdr_name tcName

因此它返回的名称首先被解释为之前的任何内容（可能是指向值的链接），然后被解释为类型构造函数。常规名称如何成为类型构造函数？我的猜测是，这是在 GHC 7.6 中对 TypeOperators 进行改革时添加的，现在它确实与值级运算符共享命名空间。

然后 haddock 匹配结果：如果第一个是类型构造函数，则使用它，否则使用第二个。所以要么它之前是一个类型构造函数，然后它就被使用了。或者不是，但是dataTcOccs要使用生成的修改版本。

在我看来，黑线鳕应该总是在这里使用第一个选项，而代码只是一个误导性的副本，从实际上可以解决多个结果时如何使用它们。

于 2013-07-29T08:21:09.390 回答
2

这是一个Haddock 错误 #228和 Neil 的Haddock 错误 #253，修复程序已经在上游发布了几个月。您可以构建 GHC HEAD 并重新构建您的文档，或者等待 7.8 并执行此操作。

于 2014-01-13T09:44:06.217 回答