Search code examples
haskellhaddock

Haddock link to functions in non-imported modules

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.

Solution

  • This was a Haddock bug #228 and Neil's Haddock bug #253 and the fix has been upstream for few months. You can build GHC HEAD and rebuild your documentation or wait for 7.8 and do it then.