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]
