GNOME Bugzilla – Bug 346959
Patch for lack of source documentation
Last modified: 2006-07-10 07:21:40 UTC
It seems the gimp core source is almost totally undocumented! Following is a patch adding some source code documentation in: app/tools/gimptransformtool.c, app/tools/gimpdrawtool.c, devel-docs/libgimpmath/tmpl/gimpmatrix.sgml, libgimpmath/gimpmatrix.c
Created attachment 68606 [details] [review] a bit of source documentation
I wonder why one would want to document a function like gimp_draw_tool_class_init(). The role of the function is clear and what it does can be easily seen by looking at the code. Adding documentation in such a place will only make the code harder to read and there is the risk that the documentation is not updated when the code changes. I will have a close look at your patch and check where the addition of comments makes sense.
My thinking is that the documentation should be robust enough to make sense after it is processed by gtk-doc, and not necessarily with the source code right there. Particularly since gtk-doc puts hyperlinks to referenced functions, unlike raw source code. Documentation is a short cut to browsing the source directly, and most new comers I would think will browse documentation before browsing source. In terms of source code docs, redundancy can be very helpful. Any documentation whatsoever runs the risk of not being updated when the code changes. Documentation, from my view, is a guide for the inexperienced, and should address the concerns that inexperienced people, such as myself, have about the code, and not Only what people who already live and breath gimp think is an interesting point. Anyway, I certainly don't think my doc comments are perfect! They are simply what I have found useful so far in trying to map out the source for my own purposes.
We don't really use gtk-doc with the core; it is not our goal to make the core understandable from just reading the generated docs. If it turns out that most newcomers use the documentation for the core, we should probably better take it offline.
I have reviewed your patch and rejected most of it except for some changes to gimpdrawtool.c. A lot of your comments were for static functions which aren't seen by gtk-doc at all. Others only revealed implementation details that the caller should not have to worry about. A few comments looked useful and I committed them to CVS after some minor changes.