#2168 closed feature request (fixed)
ghci should show haddock comments for identifier
Reported by: | j.waldmann | Owned by: | |
---|---|---|---|
Priority: | normal | Milestone: | |
Component: | GHCi | Version: | 6.8.2 |
Keywords: | Cc: | claus, pho@…, hvr, Fuuzetsu, alanz, davean, ntc2 | |
Operating System: | Unknown/Multiple | Architecture: | Unknown/Multiple |
Type of failure: | None/Unknown | Test Case: | |
Blocked By: | Blocking: | ||
Related Tickets: | Differential Rev(s): | ||
Wiki Page: |
Description (last modified by )
This came up in comp.lang.haskell recently: http://groups.google.com/group/comp.lang.haskell/msg/ae69f720377e7a3f
I like the idea.
Immediate thoughts:
- if ghci reads the source file, it can read haddock annotations
- if ghci reads the interface file only (for library modules), it needs to find the installed documentation
On the other hand the requested feature is a typical IDE functionality (cf. Eclipse/show source/show javadoc) and it's perhaps a bit much to require that from ghci.
Change History (30)
comment:1 Changed 11 years ago by
Description: | modified (diff) |
---|---|
difficulty: | → Unknown |
comment:2 Changed 11 years ago by
comment:3 Changed 11 years ago by
Milestone: | → 6.10 branch |
---|
If we want an IDE to be able to do it then we probably want the functionality to be in the GHC API, at which point GHCi may as well do it.
I don't think looking for the installed docs is a good idea; better would be to put the info in the .hi
file (or another file installed alongside the .o
and .hi
files; perhaps it would even make sense to spit the parsed source out into a file, so that we can also do things like :list?).
comment:4 Changed 11 years ago by
Cc: | claus added |
---|
the haskellmode for vim plugins have supported this for quite some time, but only for installed packages, by going the awkward route of parsing the urls out of the doc-index-*.html
files. replacing that hack with something supported by ghc would be nice.
haddock comments are often meant to be used from within a browser, with interlinkage/highlighting/etc, so the plugins call a browser, and i'd recommend ghci doing the same, separating out the need for a text/console-renderer.
that reduces the problem to
1 finding the correct base urls, which is mostly ghc-pkg responsibility (currently outside ghc api, i think) - ghc --print-docdir
would give one location; ghc-pkg field '*' haddock-html
gives all locations (the latter is a recent addition to ghc-pkg
and not yet used in the haskellmode plugins).
2 constructing the correct relative urls, which ghc api ought to provide help with
3 finding the correct tool instance (which ghc-pkg
is the one to call for the current ghci
session?). there's a ticket somewhere for this general problem, iirc.
4 do something about sources/modules not yet processed by haddock
given solutions to 2&3, accessible from within ghci, one could then use ghc-pkg
to construct the complete url for an identifier, and call a browser for it. i'd be tempted to require running haddock to avoid treating 4 specially, but a purely cmdline-based interface might be nice, too.
comment:5 Changed 11 years ago by
The documentation is stored in the Haddock interface file now, and Haddock has a library that provides access to the .haddock files. So it seems to me the right way to go is for GHCi to invoke the Haddock library to get the docs. Unfortunately this needs some restructuring: the Haddock library would become a boot package.
comment:6 Changed 11 years ago by
Cc: | pho@… added |
---|
comment:7 Changed 10 years ago by
Architecture: | Unknown → Unknown/Multiple |
---|
comment:8 Changed 10 years ago by
Operating System: | Unknown → Unknown/Multiple |
---|
comment:9 Changed 10 years ago by
Milestone: | 6.10 branch → 6.12 branch |
---|
comment:10 Changed 9 years ago by
Milestone: | 6.12 branch → 6.12.3 |
---|
comment:11 Changed 9 years ago by
Milestone: | 6.12.3 → 6.14.1 |
---|---|
Priority: | normal → low |
comment:12 Changed 8 years ago by
Milestone: | 7.0.1 → 7.0.2 |
---|
comment:13 Changed 8 years ago by
Milestone: | 7.0.2 → 7.2.1 |
---|
comment:14 Changed 7 years ago by
Milestone: | 7.2.1 → 7.4.1 |
---|
comment:15 Changed 7 years ago by
Milestone: | 7.4.1 → 7.6.1 |
---|---|
Priority: | low → lowest |
comment:16 Changed 6 years ago by
Milestone: | 7.6.1 → 7.6.2 |
---|
comment:18 Changed 4 years ago by
Milestone: | 7.10.1 → 7.12.1 |
---|
Moving to 7.12.1 milestone; if you feel this is an error and should be addressed sooner, please move it back to the 7.10.1 milestone.
comment:19 Changed 4 years ago by
Moving to 7.12.1 milestone; if you feel this is an error and should be addressed sooner, please move it back to the 7.10.1 milestone.
comment:20 Changed 4 years ago by
Cc: | hvr added |
---|---|
Type of failure: | → None/Unknown |
Like Igloo said, I think we should just add Haddock comments to the .hi files. We are already storing meta data in there such as annotations. Incidentally, if we do this then Haddock might also eventually be able to generate docs purely based on .hi files (useful in some cases).
comment:21 Changed 4 years ago by
Cc: | Fuuzetsu added |
---|---|
Priority: | lowest → normal |
Adding Mateusz who may be able to contribute some comments, as I've been bugging him for some time already about adding the raw Haddock markup to .hi
files... :-)
comment:23 Changed 3 years ago by
Cc: | alanz added |
---|
comment:24 Changed 3 years ago by
Milestone: | 8.0.1 |
---|
comment:25 Changed 2 years ago by
I am intersted in implementing this. Does anyone have any thoughts about how? Perhaps someone has already started on this a bit?
My tentative plan of attack is
- Modify ghc to include the docs in interface files (Modify IfaceSyn.IfaceDecl to optionally include docs)
- Add a :doc command to ghci
Once that is done the next step would be to modify Haddock to take advantage of this.
comment:26 Changed 2 years ago by
Adamse: I think this would be great for haddock too, and am excited someone wants to proceed! I know that a number of people have an interest in this, and am trying to get some further eyes on the proposal to confirm it makes sense, but on first glance it looks like a reasonable approach. Even step 1 on its own would be great, as an opportunity for lots of tooling (ghci included) to start making use of the data.
comment:27 Changed 2 years ago by
Doing some more investigations it might make more sense to add the docs to HscTypes.ModIface
in a fashion similar to how Haddock does in its Interface
type (a map from Names to Docs and a map from Names and argument positions to Docs). This would also add the possibility of docs for unexported entities as Haddock currently supports.
comment:28 Changed 2 years ago by
Cc: | davean added |
---|
comment:29 Changed 22 months ago by
Cc: | ntc2 added |
---|
comment:30 Changed 8 months ago by
Resolution: | → fixed |
---|---|
Status: | new → closed |
The :doc
command introduced in 85309a3cda367425cca727dfa45e5e6c63b47391 is somewhat limited – it doesn't show docs for function arguments for example. But I hope to improve it further for GHC-8.8.
The link says: