Broken links for haddock docs

[georgefst]

HLS 1.6.1, GHC 8.10.4, Cabal 3.4.0.0, MacOS.

HTML documentation seems to be totally broken for third-party dependencies. Perhaps nobody is using this feature since it's undocumented.

The Documentation link beneath the hover info leads to an almost blank page, with only the Open on Hackage link. This URL erroneously refers to the html library (which isn't even a dependency of my project) instead of the one we want to browse: e.g. https://hackage.haskell.org/package/html-1.0.1.2/docs/Data-List-Extra.html#v:splitOn instead of https://hackage.haskell.org/package/extra-1.7.10/docs/Data-List-Extra.html#v:splitOn.

[DunetsNM]

Doc links generation is imprecise, it uses a heuristic that sometimes results in a wrong location. The ultimate fix for it is to parse .haddock files. This would provides far better doc-on-hover experience with more accurate and exhaustive documentation

The bug & PR that I offered to fix it about a year ago:
haskell/ghcide#861
#731

unfortunately it didn't proceed because haddock-api simply fails to compile off hackage for some GHC versions, and it was (probably still is) against HLS policy to supply dependencies outside of hackage / for a specific git revision of haddock-api

I tried to raise and fix it upstream in haddock, afaik it's not fixed. I'm happy to contribute this PR again when haddock is fixed, or when HLS deprecates old GHC versions with broken haddock-api (whatever comes first).

[jneira]

@DunetsNM how interacts this (afaiu server specific) with the vscode specific open documentation hooks?

Recently that vscode feature got a partial fix: haskell/vscode-haskell#452. It opens directly the docs in hackage or show in a panel but with broken links

[jneira]

I tried to raise and fix it upstream in haddock, afaik it's not fixed. I'm happy to contribute this PR again when haddock is fixed, or when HLS deprecates old GHC versions with broken haddock-api (whatever comes first).

Could we link the issue/pr upstream here? thanks!

[DunetsNM]

@jneira oh I see, I guess you right ,this particular bug is in VSCode extension not the actual doc html file lookup.

the upstream haddock issue is haskell/haddock#1246

[georgefst]

Yep, this looks like a bug in with the haskell.openDocumentationInHackage option. When that's off (and docs are built, e.g. with cabal configure --enable-documentation), the local docs work correctly.

Tbh, I think rather than having haskell.openDocumentationInHackage exist at all, both options should be available, with the links to local docs only showing when they exist. Just because local docs are built doesn't mean I definitely don't want to open docs in a web browser anyway.