Idea to allow people to comment on Haskell docs

[Simon Peyton-Jones]

I think it looks great!  Just the job, thank you.

Did you modify the Haddock documentation too?

One thing to think about is what happens as the code evolves.  When you
re-generate the Haddock docs, what happens?  Since the links are done by
name (I think) it's probably not bad: you get links to the existing wiki
entries so long as the name of the function doesn't change.  If a
function is deleted, I guess there'll be an orphan wiki entry, but
that's probably ok.  Worth documenting this in the Haddock docs.

Adding source code links would complete the picture.

Simon

| -----Original Message-----
| From: Duncan Coutts [mailto:duncan.coutts at worc.ox.ac.uk]
| Sent: 19 January 2006 21:55
| To: Simon Peyton-Jones
| Cc: Haskell Libraries
| Subject: RE: Idea to allow people to comment on Haskell docs
| 
| On Wed, 2006-01-18 at 09:01 +0000, Simon Peyton-Jones wrote:
| > It looks great!  But I'd never have found the link if you hadn't
pointed
| > me at it.
| >
| > Rather than "Wiki" say "User comments".
| 
| Done.
| 
| > And I think the per-entry [User comment] link is essential.
Typically
| > people are going to be looking at a particular thing.  For example,
here
| >
| >
http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html#v
:svgRenderFromString
| > is where I'd look for the link for svgRenderFromString.
| 
| Done!
| 
| So take another look at these example pages:
| http://haskell.org/gtk2hs/docs/devel/
| http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html
| 
| For the per-entry links, to conserve space I've just said [Comments]
| rather than [User Comments] and used a smaller font. These cosmetic
| things are easy to change if anyone complains.
| 
| I've sent the haddock patches that implement this stuff to Simon
Marlow,
| so if people are generally favourable of this iteration of the patch
| perhaps he'd like to apply it. :-) I hope I've done the changes in
such
| a way that it should be straightforward to add source code links too
| if/when haddock is taught how to find the original source file for
each
| module.
| 
| So, opinions?
| 
| Duncan