ghci should show haddock comments for identifier

[j.waldmann]

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.

[igloo]

The link says:

I really like the feature (in other languages like python) which shows
you the doc string for a function or object.

For example if I type from the python interpreter:

 >> help(function)
I get the docstring of function defined as

def function():
        """ docstring for function"""

Is it possible to have something similar in haskell??
The type of the object is very useful, but a little comment would be
even better... 

[igloo]

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?).

[claus]

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.

[simonmar]

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.

[thoughtpolice]

Moving to 7.10.1.

[thoughtpolice]

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.

[thoughtpolice]

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.

[waern]

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).

[hvr]

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... :-)

[thoughtpolice]

Milestone renamed

[adamse]

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

1. Modify ghc to include the docs in interface files (Modify IfaceSyn.IfaceDecl to optionally include docs)
2. Add a :doc command to ghci

Once that is done the next step would be to modify Haddock to take advantage of this.

[gershomb]

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.

[adamse]

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.

[sjakobi]

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.