search

haskell / haskell-language-server

Official haskell ide support via language server (LSP). Successor of ghcide & haskell-ide-engine.
Apache License 2.0
2.71k stars 367 forks source link

Broken links for haddock docs #2194

Open georgefst opened 3 years ago

georgefst commented 3 years ago

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 commented 3 years ago

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: https://github.com/haskell/ghcide/pull/861 https://github.com/haskell/haskell-language-server/issues/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 commented 3 years ago

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

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

jneira commented 3 years ago

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 commented 3 years ago

@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 https://github.com/haskell/haddock/issues/1246

georgefst commented 3 years ago

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.