Pledge to Mac porters (especially the newly joined Sun developers)

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-o
oo.org/bonsai/cvsquery.cgi?branchtype=match&date=month&a
mp;branch=cws_src680_aquavcl01

(2)
http://go-
ooo.org/bonsai/cvsview2.cgi?diff_mode=context&whitespace
_mode=show&subdir=gsl/canvas/source/cairo&command=DI
FF_FRAMESET&file=cairo_cairo.cxx&rev1=1.4.30.1&r
ev2=1.4.30.2&root=/var/cvsup
(part of cws presfixes12)

-- 
Mox on G

------------------------------------------------------------
---------
To unsubscribe, e-mail: mac-unsubscribeporting.openoffice.org
For additional commands, e-mail: mac-helpporting.openoffice.org