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.