Operator Documentation Links and All Source Links don't work

[lawbel]

Apologies if this issue has already been filed and/or fixed; I did a quick search through all issues/PRs and couldn't find anything relating to this.

Your environment

I suspect that this issue would be independent of the setup, but just in case, I experienced this issue on Manjaro (Linux) using VSCode (OSS version) with the Haskell extension. I can give more details if required.

I tested this on a fresh project (meaning, I created a new dummy project just for testing) with

• GHC 8.10.7 and haskell-language-server-8.10.7~1.5.1, git hash 745ef26 to be specific
• I also tested using GHC-9.0.1 with haskell-language-server-9.0.1~1.5.1, same git hash

In both cases I go the same problem. I'll continue describing the problem as I experienced it with ghc 9.0.1.

Steps to reproduce

Open any project with HLS enabled. Find an operator, let's say =<< :: Monad m => (a -> m b) -> m a -> m b for example's sake.¹ Hover over it, to show the information about it including a 'Documentation' and 'Source' link, and then try to use those links to examine the documentation / source code for =<<.

Expected behaviour

The Documentation and Source links should work.

Actual behaviour

They do not work. The links seem to be in a different format then haddock expects.

• The documentation link takes me to the right module, but it doesn't take to the part of the page where the operator is actually defined.
• The source link doesn't seem to work at all.

Include debug information

I'm not familiar with the specifics on how haddock expects links to be formatted, but playing around with the links seems to suggest what the problem is (and what the solution would be):

Documentation link

• what HLS produced: https://hackage.haskell.org/package/base-4.15.0.0/docs/GHC-Base.html#v:=%3C%3C
• what the correct link seems to be: https://hackage.haskell.org/package/base-4.15.0.0/docs/GHC-Base.html#v:-61--60--60-

The links are the same up until the part at the end, -Base.html#v:.... Instead of ending the link with ...#v:=<< and doing URL encoding, we need to escape the name =<< according to a different scheme: escape each character in its' name according to the unicode code point value of each character, and surround it on the left and the right with a - character. That seems to be what haddock expects.

So, Data.Char.ord '=' == 61 and Data.Char.ord '<' == 60. Therefore we should escape = as -61- and < as -60-, so that we end the link with ...#v:-61--60--60-.

I attempted to test this with non-ASCII operator names as well, but found that for such operators there simply are no links provided by HLS. But for reference, haddock seems to indeed use the same approach, e.g. the link to union ∪ in containers-unicode-symbols is encoded as 8746 (0x222a) which is the unicode code point for ∪.

Source link

• what HLS produced: https://hackage.haskell.org/package/base-4.15.0.0/docs/src/GHC.Base.html#=%3C%3C
• what the correct link seems to be: https://hackage.haskell.org/package/base-4.15.0.0/docs/src/GHC-Base.html#=%3C%3C

The links are the same except for the part with the module names. Simply URL encoding the name =<< seems to be fine here, and instead there is a totally different (though I imagine easy to fix) issue here: instead of writing the module name as GHC.Base.html we must instead write GHC-Base.html. That is, replace every . in the module name with a - instead, just like the documentation links already do. This has nothing to do with operators, this issue seems to affect all source links, for operators and for non-operators.

Footnotes

1. I pick this as example because (1) it is in the prelude, (2) it has multiple different characters in its' name, and (3) it is not a class method. There seems to be an unrelated issue in haddock with source links to class methods, which seems to have been fixed by the time of ghc 9.2 and base-4.16. Everything else about this issue seems to still hold true for ghc 9.2. ↩

[jneira]

Hi, good catch, i just have reproduced it in my environment. The way urls are generated has to be slightly changed to make them work.
I dont expect it is too much difficult (you already spotted the format needed for urls). The module where it is done afaics is https://github.com/haskell/haskell-language-server/blob/master/ghcide/src/Development/IDE/Spans/Documentation.hs

[lawbel]

Thanks for the quick response! Yeah, I also have the feeling that this shouldn't be too complicated to fix. I will try and put together a PR.

[theGhostJW]

I am also having issues navigating to documentation but the issue seems different now. The following are pairs of failing links generated by HLS and working links. Compare the pair...

Note: the only difference is the suffix at the end of the ghc version eg. ghc-9.8.2-6af5 fails where as ghc-9.8.2 passes.

HLS Fail
https://hackage.haskell.org/package/ghc-9.8.2-6af5/docs/Language-Haskell-Syntax-Module-Name.html#t:ModuleName

Correct url
https://hackage.haskell.org/package/ghc-9.8.2/docs/Language-Haskell-Syntax-Module-Name.html#t:ModuleName

HLS Fail
https://hackage.haskell.org/package/containers-0.6.8-d9b8/docs/Data-Map-Internal.html#t:Map

Correct url
https://hackage.haskell.org/package/containers-0.6.8/docs/Data-Map-Internal.html#t:Map