[Haskell-cafe] Re: Haddock GSoC project
ml at isaac.cedarswampstudios.org
Fri Mar 27 22:02:27 EDT 2009
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
* 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
Resolve many Haddock Trac tickets. Specific projects: Make cross-package
documentation work; and refactor the comment-parsing out of GHC and into the
* 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
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
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
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
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
- 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.
More information about the Haskell-Cafe