Mention docs on hover feature in README

[georgefst]

Thanks to @pepeiborra at #208, I discovered that it is actually currently possible to get docs for dependencies to show up in HLS. Based on a discussion about this on IRC a few days ago, I suspect this is not widely known. Indeed, AFAICT, the -haddock flag is completely undocumented.

I don't know if this is necessarily the best part of the README in which to mention the workaround for this, but I feel it ought to be in there somewhere.

I was also unsure whether it's worth explaining how to specify a GHC flag for dependencies of a project, and which method to mention for doing so. Personally, I've just decided to bite the bullet and go with:

program-default-options
  ghc-options: -haddock

in my global cabal config, but I'd guess that's not suitable for everyone.

[jneira]

Hi!, thanks for the doc addition. I think cabal configure alternative is better, cause it is per project but maybe we could include both alternatives, global and project local.
I think we should add some info for stack users: ideally the stack counterpart to the cabal alternative you have used.

[pepeiborra]

To me it makes perfect sense to put this in the global cabal config. If in doubt, why not document both the global and project setting?

[pepeiborra]

Worth noting that the -haddock flag can currently cause compilation errors due to invalid Haddock markup; this will change in 8.12 assuming !2377 gets merged in time.

[jneira]

I think we should add some info for stack users: ideally the stack counterpart to the cabal alternative you have used.

the stack equivalent is to set in $STACK_ROOT\config.yaml (globally) or in ./stack.yaml (per project):

 ghc-options:
  "$everything": -haddock

I've tested it locally and it makes docs appear in hover

[jneira]

HLS. Based on a discussion about this on IRC a few days ago, I suspect this is not widely known. Indeed, AFAICT, the -haddock flag is completely undocumented.

From ghc issue https://gitlab.haskell.org/ghc/ghc/-/issues/14920 the -haddock flag was documented with https://gitlab.haskell.org/ghc/ghc/commit/c35c545d3f32f092c52052349f741739a844ec0f so it should be shown in the next ghc release docs (??)
EDIT: It is in master docs: https://ghc.gitlab.haskell.org/ghc/doc/users_guide/using.html#haddock

[georgefst]

After living with -haddock enabled globally for a day, I think I can recommend it. I've built several large packages, and the only place I've hit an issue is c2hs.

It is, however, a little painful when things do go wrong, since -no-haddock isn't yet available (it's in GHC master, but no release yet).

Thanks @jneira for the stack syntax - I wouldn't have been sure of that.

[georgefst]

Kind of feels like this belongs in a footnote, but I seem to remember Github markdown doesn't really support them.

[jneira]

It is, however, a little painful when things do go wrong, since -no-haddock isn't yet available (it's in GHC master, but no release yet).

I think this is a good reason to not recommend seting it globally by default