[Haskell-cafe] Re: Haddock GSoC project

[Isaac Dupree]

Okay, I've written a draft Haddock-GSOC application: would any of you like to 
review it / suggest how it could be improved? (or should I just submit it to 
Google?)  I'm particularly wondering whether my proposed time-line seems 
realistic. -Isaac

    * What is the goal of the project you propose to do? 

To improve Haddock, the Haskell documentation tool, both substantively in the 
short term and to be better factored in the long term.

    * Can you give some more detailed design of what precisely you intend to 
achieve? 

Resolve many Haddock Trac tickets.  Specific projects: Make cross-package 
documentation work; and refactor the comment-parsing out of GHC and into the 
Haddock code-base.

    * What deliverables do you think are reasonable targets? Can you outline 
an approximate schedule of milestones? 

In the first week I will get Haddock and GHC compilation and patch-making set 
up, fix some minor bugs and send/apply the fixes.

Next I will start to determine and converse about the implementation 
difficulties with making Haddock work across packages.  At the same time, I'll 
continue working on more minor bugs/features (increasing my familiarity with 
the code and with the coding process).

By the end of June I hope to get cross-module docs working. [Is this a 
realistic goal?]

By this time, I'll have some familiarity with the parsing code (having fixed 
some of its bugs/infelicities), and I can confront the problem of how to 
refactor the comment-parsing out of GHC.  I can imagine I might only be able 
to find a partial solution easily, but I'll do whatever I have time for.  
Optimistic timeline to finish this by the end of July; if I get ahead of 
schedule, I'm sure I'll know enough about Haddock's infelicities by then to 
know other mini-projects that would be worth doing.  For example, I could 
improve the layout of the index page Haddock generates (Python docs do it 
better, for reference, according to 
<http://trac.haskell.org/haddock/ticket/70>.)

Due to the process of testing my changes, I might even write some 
documentation, if I see an atrociously documented function in some library :-)

    * In what ways will this project benefit the wider Haskell community? 

Better documentation (documentation that is less difficult to successfully 
write) makes everything flow more smoothly in source-code-land.  Especially 
core (even Haskell-98) library documentation has broken multiple times due to 
Haddock deficiency, and other library authors suffer from everything from `type` 
annotations not working, to Haddock-2 parsing being more strict, to... every 
possible issue, really.

The cross-package documentation failure specifically makes people reluctant to 
refactoring into smaller packages, even when that would increase code re-use.

Making Haddock/GHC more composable should make it easier for everyone to make 
small improvements to Haddock, without delving into GHC as much.  Perhaps it 
might even make possible some new tool different from Haddock that looks at 
information in comments, should someone desire such a thing.

    * What relevant experience do you have? e.g. Have you coded anything in 
Haskell? Have you contributed to any other open source software? Been studying 
advanced courses in a related topic? 

I substantially improved Spiderweb Software's scenario-editor for Blades of 
Avernum (once they made it open-source), adding 3D support and other 
improvements.  (C programming language).

I worked on Battle for Wesnoth scenarios some, and I hacked on the C++ code 
for lexing/parsing their markup language, and I learned my lesson when I 
failed to coordinate successfully with the development team. :-)  They used 
Doxygen to document their code, though it was not used nearly as thoroughly 
(at least, not back a few years ago) as a lot of Haskell code is documented 
today.

I hacked on GHC, and this code has been committed: I improved the parsing of 
negative unboxed literals, and I refactored several places in the code that 
used language extensions unnecessarily.  Also I've contributed to discussions 
on Haskell development mailing-lists over the years (leading to at least one 
bug-fix), and reported several more bugs in Trac as I ran into them while 
hacking in Haskell.

I took an advanced-level Artificial Intelligence class in which I programmed in 
Haskell and got an A.  I've read many research papers related to Haskell or 
compilation.  I've used Darcs; I've used Linux and followed its open-source 
coordination travails for four years now (formerly I used Mac OS).  I know 
(X)HTML and CSS well enough to write my own W3C-validated webpage (and my 
parents work in web-design so I hear a lot about it), so I should be able to 
work on Haddock's HTML-generating code easily.

    * In what ways do you envisage interacting with the wider Haskell 
community during your project? e.g. How would you seek help on something your 
mentor wasn't able to deal with? How will you get others interested in what 
you are doing? 

I'll start a Haskell-related blog that I update at least weekly with what I've 
been doing, and I'll be on IRC.  If there's a problem... probably my mentor 
will know who to ask anyway, because they're people who are knowledgeable in 
the Haskell community.  Likely mailing lists include glasgow-haskell-users, 
cvs-ghc, haskell-cafe, libraries; IRC can be good for resolving some 
difficulties.  Sometimes I should just spend more time meditating on / working 
on the problem myself; sometimes deciding that it's not a priority, and 
working on something that I do know how to make progress on, is the best step.  
I'll try and get people excited when I make progress on something really user-
visible :-)... but at least half of what I'll be doing is probably not that 
exciting to most people and doesn't need to be (it'll just make their lives 
easier in the future).

    * Why do you think you would be the best person to tackle this project? 

I've been hacking with Haskell (and other languages) for several years.  This 
specific project aligns with some of my interests (especially, parsing, and 
easy-to-use documentation).

When there's a conflict on what some code should look like, I'm easygoing -- 
I'll try to look for a perfect solution, but if that's too hard/impossible I 
look for a compromise, and I think I have a pretty good sense of when to do 
that (what's likely to be possible, with how much work), from
- hacking, myself, and finding some things more time-consuming than I had 
presumed, and some easier;
- listening to Haskell and other mailing-list arguments for years, and 
occasionally participating;
- having a mentor knowledgeable in Haddock/GHC code who can help estimate 
things for me and with me.
I don't mind if I don't get fame and fanfare, but I've learned also that it's 
best not to work in a dark corner either -- to communicate early and often, 
when a design decision needs to be made, so that several different people's 
perspectives (if needed) can be taken into account.