Hover docs including links for dependencies

[georgefst]

As it stands, it seems that Haddock docs show up for boot libraries, and the project being developed, but not for third party libraries from Hackage.

I would guess (without really knowing anything about the current implementation) that if the dependencies have been installed with documentation (e.g. documentation: True in the global cabal config file), then the logic wouldn't be that different to the way it currently works for boot libraries - i.e. HLS just needs some way to know the path to the .haddock files.

I'd be keen to take a look into this if no one currently is. But I would need some pointers.

[jneira]

A possible workaround is to active documentation generation for all dependant packages adding in the cabal.project:

package * 
  documentation: true

(tip credits for @fendor)
It will make the build really slow but it can be done ocasionally.

The hoogle plugin would add docs for dependent packages included in its default set. In the practice they are quite used so you would cover docs for many deps.

[pepeiborra]

Ignoring the hoogle plugin, currently hls/ghcide glean Haddocks from interface files. For interface files to contain Haddocks, ghc must be called with the -haddock flag.

Unfortunately, I don't believe Cabal currently knows about this ghc flag, regardless of the documentation:True setting [1]. You could work around this yourself by telling cabal to use this flag when compiling dependencies in the cabal.project file, or if using stack, in the stack.yaml file.

For Nix, I have sent a PR [2] to add a setting for this, although it will not be the default until 8.12

[1] - haskell/cabal#6825
[2] - NixOS/nixpkgs#91557

[jneira]

Ignoring the hoogle plugin, currently hls/ghcide glean Haddocks from interface files. For interface files to contain Haddocks, ghc must be called with the -haddock flag.

There is a open issue about implementing the plugin, maybe we should closing it with a note.

[georgefst]

Thanks @pepeiborra, I didn't know about that flag!

Not sure what the long-term solution is here then, but for now it seems like it might be worth mentioning in the README that this can be worked around with something like cabal configure --ghc-options=-haddock. Of course, that does cause everything to be rebuilt, and I suspect the build takes a lot longer than without it...

[pepeiborra]

@georgefst better documentation would help, but at the moment my setup is Nix based and I don't use either stack or cabal.project style builds, so I'm not in a good position to give advice about this. If you could send a PR documenting the approach that works for you, it would be a fantastic contribution.

[jneira]

@pepeiborra thanks for the clarification about how hls/ghcide hover works.

I think we should update hls itself cabal.project and stack.yaml dropping the documentation flags and adding the -haddock ghc options cause afaik the main goal for adding them was precisely get docs on hover.

I've tested locally that using -haddock show docs but no using documentation: true, did it work for you @fendor?

[jneira]

As hie-bios can use a specific stack.yaml (and there is a request to be able to set a specific cabal.project), the -haddockoption could be in those specific config files as workaround if the option interferes with normal building (making it slower or fail).
Beyond that the unique way to make some progress (avoid the need to generate haddock docs for all dependencies) would be port the hoogle plugin.

[georgefst]

As well as #209, we ought to document that --enable-documentation is required to get the Documentation link to appear with the hover text.

Should we keep things simple and just tell users to enable it globally in addition to -haddock?

[jneira]

As well as #209, we ought to document that --enable-documentation is required to get the Documentation link to appear with the hover text.

Should we keep things simple and just tell users to enable it globally in addition to -haddock?

I think we should add a note about --enable-documentation in the existing section suggesting add -haddock` (https://haskell-language-server.readthedocs.io/en/latest/configuration.html#how-to-show-local-documentation-on-hover)

@georgefst would you like and have time to open a pr adding it?

[georgefst]

@jneira I'm sure it's a fairly quick change but I'm pretty swamped at the moment.

I also don't know the stack syntax off-hand, and there are probably caveats to mention (increased compile times? I'm not sure whether this is negligible in practice).

[jneira]

dont worry will try myself, thanks anyways!

[rami3l]

I don't know if it's related or not, but u/2435191 and I have encountered this strange behavior of base hover docs not working, quote:

[...] when hovering over a builtin function only type information comes up, not the actual docstring of the function [...] (Interestingly, the "Documentation Source" link leads me to the web docs, but I don't want to click everytime.)

Original Post

@jneira Do you happen to have any clue on this one?

[July541]

@rami3l Looks like it's on ghc-9.0, docs is known missing, see https://gitlab.haskell.org/ghc/ghc/-/issues/20903.

[rami3l]

@July541
Thanks a lot for your reply!
This turned out to be more complicated than it seems however...

After upgrading the compiler to GHC 9.2.2 (or more precisely, after using stack snapshot nightly-2022-06-06),

VSCode on my Ubuntu box gives me this, which is expected:

However, my Mac gives me this:

... and I have no idea how to fix this. If you need more info on this, please feel free to ask me!

[July541]

@rami3l That's amazing, I always thought that only ghc-9.0 had this problem, but I found both ghc-9.2.2 and 9.2.3 are also not shipping the docs. Worth raising a ticket for ghc devs.

Update:
I compiled ghc on local and docs works fine.

[rami3l]

@July541
You mean there could be some problems with the precompiled GHC binaries?

[July541]

You mean there could be some problems with the precompiled GHC binaries?

Yes I think.

[rami3l]

@July541
My apologies for my not having much experience interacting with the GHC team, but anyway I sent a comment in GHC/#20903.

[July541]

@rami3l Many thanks for your timely reminder :)

[rami3l]

@July541
Just bring curious: a month later I still didn't get any reply from GHC... Is that thread the wrong place to post?

[July541]

Just bring curious: a month later I still didn't get any reply from GHC... Is that thread the wrong place to post?

GHC devs are slow to respond to some low-priority jobs I think.

And thanks to ghcup, compiling ghc from source is much easier than before, I've turned to build ghc from source to make docs available.

[rami3l]

Update: This is indeed an issue with prebuilt GHC releases from ghcup. I don't know about newer GHC 9.2.x versions, but updating to GHC 9.4.4 works for me on macOS.

Many thanks to all of you!