documentation/ folder breakdown?
Might just be missing it, but is theredocumentation on the code, what's in the different folders, what classes do what, what needs to be changed for a port to a new platform? http://webkit.opendarwin.org/projects/documentation/index.html thanks
On Friday 14 July 2006 18:46, schmindor wrote:
Might just be missing it, but is theredocumentation on the code, what's in the different folders, what classes do what, what needs to be changed for a port to a new platform?
http://webkit.opendarwin.org/projects/documentation/index.html
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
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
Don't disagree but I'd love to see some of the experts in each area do some high level flows. Higlighting main entry points would be good. Techtips on a few methods techniques would be helpful. A good topic would be how a page loads highliting a few core classes. In general I'm fine with reading the code but overviews like this are really valuable for example I do little with the js engine so if I had to chase a bug into there having a handy overview would be very useful. Its a big enough code base that becoming familar with all of it is not feasible for most. On 7/14/06, David D. Kilzer <ddkilzer@kilzer.net> wrote:
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
_______________________________________________ webkit-dev mailing list webkit-dev@opendarwin.org http://www.opendarwin.org/mailman/listinfo/webkit-dev
On Friday 14 July 2006 22:30, Mike Emmel wrote:
Don't disagree but I'd love to see some of the experts in each area do some high level flows.
Higlighting main entry points would be good.
Techtips on a few methods techniques would be helpful.
A good topic would be how a page loads highliting a few core classes.
It would be nice with well-defined contracts/interfaces for wide-spread classes such as AtomicString(and other WTF stuff), instead of that the code does whatever it happens to do in a particular revision. Cheers, Frans
participants (4)
-
David D. Kilzer
-
Frans Englich
-
Mike Emmel
-
schmindor