Opened 10 years ago

Last modified 7 months ago

#2168 new feature request

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

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 (29)

comment:1 Changed 10 years ago by igloo

Description: modified (diff)
difficulty: Unknown

comment:2 Changed 10 years ago by 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... 

comment:3 Changed 10 years ago by igloo

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 10 years ago by claus

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 10 years ago by 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.

comment:6 Changed 9 years ago by PHO

Cc: pho@… added

comment:7 Changed 9 years ago by simonmar

Architecture: UnknownUnknown/Multiple

comment:8 Changed 9 years ago by simonmar

Operating System: UnknownUnknown/Multiple

comment:9 Changed 9 years ago by igloo

Milestone: 6.10 branch6.12 branch

comment:10 Changed 8 years ago by igloo

Milestone: 6.12 branch6.12.3

comment:11 Changed 7 years ago by igloo

Milestone: 6.12.36.14.1
Priority: normallow

comment:12 Changed 7 years ago by igloo

Milestone: 7.0.17.0.2

comment:13 Changed 7 years ago by igloo

Milestone: 7.0.27.2.1

comment:14 Changed 6 years ago by igloo

Milestone: 7.2.17.4.1

comment:15 Changed 6 years ago by igloo

Milestone: 7.4.17.6.1
Priority: lowlowest

comment:16 Changed 5 years ago by igloo

Milestone: 7.6.17.6.2

comment:17 Changed 3 years ago by thoughtpolice

Milestone: 7.6.27.10.1

Moving to 7.10.1.

comment:18 Changed 3 years ago by thoughtpolice

Milestone: 7.10.17.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 3 years ago by 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.

comment:20 Changed 3 years ago by waern

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 3 years ago by hvr

Cc: Fuuzetsu added
Priority: lowestnormal

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:22 Changed 2 years ago by thoughtpolice

Milestone: 7.12.18.0.1

Milestone renamed

comment:23 Changed 23 months ago by alanz

Cc: alanz added

comment:24 Changed 22 months ago by thomie

Milestone: 8.0.1

comment:25 Changed 12 months ago by 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.

comment:26 Changed 12 months ago by 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.

comment:27 Changed 12 months ago by 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.

Last edited 12 months ago by adamse (previous) (diff)

comment:28 Changed 12 months ago by davean

Cc: davean added

comment:29 Changed 7 months ago by ntc2

Cc: ntc2 added
Note: See TracTickets for help on using tickets.