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.