Correct way to build a project in order to have Haddocks displayed on hover

[Kleidukos]

Your environment

haskell-language-server version: 2.7.0.0
editor: neovim

What's wrong?

It appears that the haddocks of an identifier are unreliably shown.

For a local identifier, no problem

But for dependencies it's not a granted.

I have a cabal.project file with the following:

packages: ./          
with-compiler: ghc-9.4
documentation: True   
                      
package *             
  documentation: True 

What am I missing? I thought I had covered all the cases?

Debug information

Build log:

Build profile: -w ghc-9.4.8 -O1
In order, the following will be built (use -v for more details):
 - os-string-2.0.2 (lib) (requires build)
 - hashable-1.4.4.0 (lib) (requires build)
 - unordered-containers-0.2.20 (lib) (requires build)
 - relude-1.2.1.0 (lib) (requires build)
 - cabaltest-0.1.0.0 (lib) (dependency rebuilt)
 - cabaltest-0.1.0.0 (exe:cabaltest) (dependency rebuilt)
Starting     os-string-2.0.2 (lib)
Building     os-string-2.0.2 (lib)
Haddock      os-string-2.0.2 (lib)
Installing   os-string-2.0.2 (lib)
Completed    os-string-2.0.2 (lib)
Starting     hashable-1.4.4.0 (lib)
Building     hashable-1.4.4.0 (lib)
Haddock      hashable-1.4.4.0 (lib)
Installing   hashable-1.4.4.0 (lib)
Completed    hashable-1.4.4.0 (lib)
Starting     unordered-containers-0.2.20 (lib)
Building     unordered-containers-0.2.20 (lib)
Haddock      unordered-containers-0.2.20 (lib)
Installing   unordered-containers-0.2.20 (lib)
Completed    unordered-containers-0.2.20 (lib)
Starting     relude-1.2.1.0 (lib)
Building     relude-1.2.1.0 (lib)
Haddock      relude-1.2.1.0 (lib)
Installing   relude-1.2.1.0 (lib)
Completed    relude-1.2.1.0 (lib)
Preprocessing library for cabaltest-0.1.0.0..
Building library for cabaltest-0.1.0.0..
Preprocessing library for cabaltest-0.1.0.0..
Running Haddock on library for cabaltest-0.1.0.0..
  50% (  1 /  2) in 'MyLib'
  Missing documentation for:
    Module header

src/MyLib.hs:14:1: warning: [-Wunused-top-binds]
    Defined but not used: ‘test’
   |
14 | test = someFunc
   | ^^^^
Documentation created:
/home/hecate/Téléchargements/test/cabal-test/dist-newstyle/build/x86_64-linux/ghc-9.4.8/cabaltest-0.1.0.0/doc/html/cabaltest/
Preprocessing executable 'cabaltest' for cabaltest-0.1.0.0..
Building executable 'cabaltest' for cabaltest-0.1.0.0..
[2 of 2] Linking /home/hecate/Téléchargements/test/cabal-test/dist-newstyle/build/x86_64-linux/ghc-9.4.8/cabaltest-0.1.0.0/x/cabaltest/build/cabaltest/cabaltest [Library changed]

[ildar-shaymukhametov]

Same issue. After executing stack haddock, I still cannot see the docs in neovim. But I can open them with stack haddock --open, which opens file:///home/ildarshaymukhametov/repos/advent-of-code/2016/haskell/.stack-work/install/x86_64-linux/a1da4e61d6fe6ceb1ffd15968ecf7cd6268b99fc0178a59832e51f24d473d876/9.4.8/doc/all/index.html
This page shows the docs for many packages including relude (which is the package I want the docs for). The docs for basic ("non-relude") things is ok, however

[fendor]

The package needs to be compiled with -haddock, not documentation: True, so the cabal.project needs to contain:

package *
  ghc-options: -haddock

Then the haddock documentation is embedded into the .hi file and we can read it!

[michaelpj]

Gosh, is this really still a problem? Is there a cabal bug here? Should documentation: true not imply that GHC option?

[Bodigrim]

I think ghc-options: -haddock is a relatively new development, very likely missed by Cabal.

[ildar-shaymukhametov]

Thanks! It worked!

For stack:
I had to build it with cabal build + cabal.project, however, to make it work
I have two folders now: .stack-work and dist-newstyle
If I do cabal clean it no longer works
Maybe it can be done with stack somehow?
Adding -haddock to package.yaml does not work, by the way
If not, I guess I shall have to do with this mixing xD

[jhrcek]

Not sure how to do it via package.yaml, but in stack you can enable building haddocks for all your dependencies by putting this at the top level of you stack.yaml:

ghc-options:
  "$everything": -haddock

See https://docs.haskellstack.org/en/stable/yaml_configuration/#ghc-options for details.

[ildar-shaymukhametov]

@jhrcek Yep! It worked!

Thanks guys!

[emlautarom1]

For those that use cabal, edit the ~/.config/cabal/config file:

program-default-options
  ghc-options: -haddock

This enables docs globally (not sure why this is not the default)

[fendor]

(not sure why this is not the default)

Just fyi, because on older GHC versions, haddock errors, such as

foo x = x
  -- | otherwise ...

would result in a hard-error.