From: "eric.bachard" <[EMAIL PROTECTED]>
Sent: Feb 21, 2007 3:21 AM
To: [email protected]
Subject: Re: [mac] Beginning documenting Salframe
Hi Tino,
tino rachui a écrit :
Damien Duportal wrote:
I welcome your laudable effort to provide more and better
documentation
for vcl in particular.
Me too : we need to document everything we can in vcl.
However what about putting the documentation
you've already started inside the actual header/source files?
This is
the place where it belongs when it comes to interfaces,
implementation
and other kind of more lower level descriptions.
Sorry but a wiki page is the wrong place for that purpose. :(
Yes, you are right this type of documentation would be better in
headers. In a perfect world, people writing the code are the best
people
to do that.
But this is not the case ( for both : we are not in a perfect
world, and
people have not always the time ... etc )
As reminder, the context : how debug the refresh and fix some events
issues ? Second : more we are to understand, more interesting can
be the
work for the community.
Because we miss all these informations, I asked Damien to document
the
code with high level documentation : describe the design, and the
ideas
behind the code, including important informations we can easely
retrieve
in the code.
But Damien just started the works, and we can understand this is
not so
easy :-)
@Damien :
For example: write short text/ sentences, providing objectives,
saying
we need to do that ( this_function() ) , and that
( another_function()
) , replacing that (old_win_function() in Windows implementation, or
obsolete ( old_qd_function() ) ..etc
+ class diagrams + list of functions classified by domain of
actions .. etc
+ describing naming conventions
+ what does not work (and why ) , how replace, workaround ..
A good tool for create diagrams / documentation is Doxygen
( available
on Mac OS X ).
Some examples :
Very good documentation is :
http://eric.bachard.free.fr/mac/vcl/archives_docs/nativemenus.sxw
written by Stephan Schaefer, and containing the essential about
nativemenus
Or another one, I know well too :
http://eric.bachard.free.fr/mac/vcl/archives_docs/
vclNativeWidgetProposal.sxw
Less important, I often read the short document I wrote for
aquacolors
cws :
http://eric.bachard.free.fr/mac/aquacolors/documentation/
maquacolors_dev_notes.pdf
FYI, you can find some other old docs here :
http://eric.bachard.free.fr/mac/vcl/archives_docs/
For high level design descriptions (e.g. diagrams and other kind of
documentation artifacts) a wiki page might be the appropriate place.
We all agree !
Last but not least, all people are invited to contribute, and help
Damien :-)
Regards,
Eric
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
