Description
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.1 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
-
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. ↩