If the code is readable, e.g., method names and variable names have descriptive names, and the methods aren't too large, reading the code is much quicker than reading the documentation (in my opinion). I would agree that some classes could use overview descriptions to give them more context, but that may be because I don't have a complete picture of all parts of the code (yet). As far as figuring out what needs to be worked on for a port, the best advice I have is to try it out to see what breaks. You might also consider hopping on IRC and asking about what needs to be done. http://webkit.opendarwin.org/contact.html Dave On Fri, Jul 14, 2006 at 07:06:12PM +0000, Frans Englich wrote:
Exactly. It's surprising so little attention is payed to documentation while other quality assurance approaches are quite good. I would almost added f commit policy for that code should be documented. Just as that it should pass tests, be reviewed and so on.
I think someone should deploy Doxygen. It doesn't necessarily involve much work, just adding Doxygen helps a lot. For example, for Patternist, KDE's XQuery/XPath 2.0/XSL-T 2.0 implementation, understanding the code is much easier with DOxygen and that's even though almost only @short tags are written:
http://patternist.sourceforge.net/documentation/API/
Cheers,
Frans