Hi,
Looking at bonsai on aquavcl01, it is quite easy to keep up with what
is actually happening in the code (1). However, all that information
will not be quickly accessible after a few months, since the code
itself does not carry that information.
During this spring, there was already some good progress on
documenting the (main) functions of the aqua port, by few porters. See
e.g.
vcl/aqua/source/gdi/salatslayout.cxx
I have also done my share in vcl/aqua/source/gdi/salbmp.cxx and in (2)
It is very important to share the understanding of the code behaviour,
especially in large open source projects like OpenOffice.org. The code
should be easily understandable to the newcomers.
I'm already thankful for the single-line comments that are here and
there in the code, but there is a need for documenting also the main
functions (as whole), especially for the cases that one a) extends the
function implementation b) wants to use that function elsewhere in the
code.
Note that I'm not asking to document _every_ function, just the most
important ones / ones that are essential parts of the API
...
By legacy, e.g. vcl has code documentation in the headers. However, I
feel that approach is not optimal similarly as the specification
documentation is not optimal:
The most fast and effective understanding of the code can be reached
when a person can read the function (i.e. API), its implementation and
its documentation in _one_ place, next to each other.
Documenting the functions directly in the source seem to be a
behaviour favored by many successful community-oriented projects.
Best Regards,
Mox
(1)
http://go-ooo.org/bonsai/cvsquery.cgi?branchtype=match&date=month&branch=cws_src680_aquavcl01
(2)
http://go-ooo.org/bonsai/cvsview2.cgi?diff_mode=context&whitespace_mode=show&subdir=gsl/canvas/source/cairo&command=DIFF_FRAMESET&file=cairo_cairo.cxx&rev1=1.4.30.1&rev2=1.4.30.2&root=/var/cvsup
(part of cws presfixes12)
--
Mox on G
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
