Idea to allow people to comment on Haskell docs

[Simon Marlow]

Duncan Coutts wrote:
> On Wed, 2006-01-18 at 09:01 +0000, Simon Peyton-Jones wrote:
>
>> On a closely related matter, Benjamin Pierce told me how often he wished
>> that there was a link from the Haddock documentation to the source code
>> for a function.  Especially for Prelude functions, he's dead right.  So
>> another really useful Haddock enhancement would be the ability to add
>> links to the source code from the Haddock docs --- again on a
>> per-function basis.  Do you feel like adding that too?   Where should
>> the code live?  I'd suggest snap-shoting it at the moment that the
>> Haddock docs are generated, and putting the files with the Haddock docs.
> 
> I was thinking about that. It'd probably be a less difficult change to
> haddock to get it to link to the source code, rather than picking it up
> as it parses it.
> 
> Haddock does know the file name of each .hs file since it's invoked with
> then on the command line. We can assume that the --source=URL points to
> the location where haddock was invoked from. This gives us the full url
> of each .hs file (I think). Then to deal with the use of pre-processors
> etc, haddock should pickup the {-# LINE ... #-} pragmas just like ghc
> does, so that it can discover the original file name.

Picking up the LINE pragmas is the way to go, yes.  The reason we don't 
get source links currently is because Haddock doesn't understand the 
LINE pragmas, so it can't find its way to the original source file for 
preprocessed files.  Most of our library code is preprocessed one way or 
another, even if it's just literate.

To get a per-function source code link, we'd need to turn the original 
source files into HTML in order to add anchors (using Malcolm's hscolour 
would be good too, and didn't the programmatica folks have a nice source 
code markup tool?).

I don't think that inserting the source code directly in the 
Haddock-generated HTML would work too well, even if it is hidden by 
default, because many definitions will refer to auxiliary functions that 
aren't part of the visible interface.

So there are now two per-entity links we need in Haddock: user comments 
and source code, and there might be more in the future (version 
history?).  So I suggest we have a little row of icons at the far right 
of each entity's definition, with pop-up descriptions when you hover 
over them.

Cheers,
	Simon