[Haskell-cafe] Re: Haddock GSoC project

[Simon Marlow]

Isaac Dupree wrote:
> I'm interested in being a GSoC student, and the Haddock-related tickets looked 
> like a good place to start
> http://hackage.haskell.org/trac/summer-of-code/ticket/1567
> http://hackage.haskell.org/trac/summer-of-code/ticket/1568
> http://hackage.haskell.org/trac/summer-of-code/ticket/1569
> 
> .... haddock could use some love!  And I love documentation.
> 
> I think I'd start by hacking on some relatively easy Haddock tickets to find my 
> way around the code and the hacking process.  Then it might be time to move 
> into one of the bigger projects (I'm tempted to say #1567, "Haddock: allow 
> documentation to propagate between packages"), depending on priorities; 
> probably still working on some smaller but important Haddock tickets.  Then it 
> depends how much time we have left in the summer, there's a lot that can be 
> done!
> 
> - I've hacked on the GHC lexing/parsing code a bit, and I know darcs, haskell, 
> etc., and I've been around watching on mailing-lists since before Haddock 2.x, 
> so I feel like I have a fair amount of context with which to approach this 
> project.
> 
> What do you think, is this a good project to look towards?  What's the next 
> step... should I elaborate my proposal by looking at Haddock tickets and their 
> priorities?  But I should have your feedback first; what do the mentors, or the 
> Haskell community, want most to be improved about Haddock?

Obviously I think these tickets are important, since I wrote them :-)  In 
terms of priority, I think #1567 is at the top: not having this harms our 
ability to reorganise and abstract things, it puts an arbitrary barrier 
between packages.  It's possible my perspective is slightly skewed though, 
since most of the packages that are affected by this are in GHC's core 
package collection.

#1568 is just refactoring, but it's a high priority: we need to get this 
code out of GHC and back into Haddock.  This is important for Haddock's 
long term future and general maintainability, though it won't have any 
visible effect on the way Haddock works.

The index page really isn't working right now, since we added the 
search-box functionality it has become unusable for the GHC library docs 
(small libraries are ok).  Thank goodness we have Hoogle and Hayoo.  We 
should really just revert to the old A-Z links, I'm not sure if there's a 
Haddock ticket for this.

There's lot of other stuff that could be done.  For instance I'd really 
like someone with some CSS expertise to have another go at Haddock's HTML 
layout.

Cheers,
	Simon