Skip to content

Mention docs on hover feature in README#209

Merged
jneira merged 2 commits intohaskell:masterfrom
georgefst:readme-haddock
Jul 23, 2020
Merged

Mention docs on hover feature in README#209
jneira merged 2 commits intohaskell:masterfrom
georgefst:readme-haddock

Conversation

@georgefst
Copy link
Copy Markdown
Collaborator

@georgefst georgefst commented Jul 19, 2020 •
edited
Loading

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
Copy link
Copy Markdown
Member

jneira commented Jul 20, 2020

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
Copy link
Copy Markdown
Collaborator

pepeiborra commented Jul 20, 2020

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
Copy link
Copy Markdown
Collaborator

pepeiborra commented Jul 20, 2020

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
Copy link
Copy Markdown
Member

jneira commented Jul 20, 2020

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
Copy link
Copy Markdown
Member

jneira commented Jul 20, 2020 •
edited
Loading

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
Copy link
Copy Markdown
Collaborator Author

georgefst commented Jul 20, 2020

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
Copy link
Copy Markdown
Collaborator Author

georgefst commented Jul 20, 2020

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

@jneira jneira mentioned this pull request Jul 20, 2020
Merged
@jneira
Copy link
Copy Markdown
Member

jneira commented Jul 20, 2020

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

@jneira jneira merged commit 4fb4998 into haskell:master Jul 23, 2020
georgefst added a commit to georgefst/haskell-language-server that referenced this pull request Jul 29, 2020
@georgefst
Fix haddock parse error in install.hs
605d19a 
Seeing as, since haskell#209, the README suggests globally enabling `-haddock`, it's rather unfortunate for that not to work with HLS' own installation script...
@georgefst georgefst mentioned this pull request Jul 29, 2020
Merged
fendor pushed a commit to fendor/haskell-language-server that referenced this pull request Aug 10, 2020
@georgefst @fendor
Fix haddock parse error in install.hs
2cb4a9c 
Seeing as, since haskell#209, the README suggests globally enabling `-haddock`, it's rather unfortunate for that not to work with HLS' own installation script...
pepeiborra pushed a commit that referenced this pull request Dec 27, 2020
@ndmitchell @cocreature
Copy notes from #183 (#209)
f89d2d6
@georgefst georgefst mentioned this pull request Sep 14, 2021
Open
@georgefst georgefst mentioned this pull request Jan 8, 2022
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jneira jneira jneira approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@georgefst @jneira @pepeiborra