Subject: First class documented (commit)
From: Jesper Skov (jskov@redhat.com)
Date: Fri Dec 29 2000 - 11:13:08 CST
Hi
I've tried to add some documentation for the fp_Container class. I
know it's not exactly a high-profile class, but I hope we can use it
to discuss comment style. Have a look here:
http://zoftcorp.adsl.dk/abi/class_fp_Container.html
I can see I've been a little inconsisten in how the brief descriptions
are worded, e.g.:
Returns foobar
vs.
Return foobar
Do people want a period (.) after the brief comments and
argument/retval descriptions?
The list of public methods should (IMO) be sorted. I've even set that
option, but it appears to be broken.
OK, I admit the above is probably ridiculous to discuss, but I figure
since we're starting from a clean slate, we might as well try to make
things consistent by setting a style guide (subtly improving the
quality of the documentation).
If I don't get any feedback on this issue, I'll toss a coin and make
some arbitrary decisions :)
Either way, I'll make the stuff I just comitted consistent as well as
add a little style guide on the front page.
Another thing I hope to accomplish with documenting just a single
class to start with, is getting others to help. I don't want to fill
in all that documentation on my own, nor do I think we should make a
chore out of it. Simply fill in a few function / attribute comments as
you come across undocumented stuff in your daily hacking - in
particular if you find you spend a while to figure out what is going
on: save the next person from the same trouble.
Thanks,
Jesper
Suppress brief descriptions at the top of the doc (looks messy).
Add brief descriptions to fp_Container class.
Make setX and setY use clearScreen() instead of duplicating it.
Deleted unused containsPoint() declaration.
CVS: ----------------------------------------------------------------------
CVS: Enter Log. Lines beginning with `CVS:' are removed automatically
CVS:
CVS: Committing in .
CVS:
CVS: Modified Files:
CVS: .doxygen.cfg text/fmt/xp/fp_Column.cpp text/fmt/xp/fp_Column.h
CVS: ----------------------------------------------------------------------
This archive was generated by hypermail 2b25 : Fri Dec 29 2000 - 11:13:13 CST