Eric: I think that I can assist Damien in documenting VCL but this will require collaboration.
My next project after fixing the README is to convert the qatesttool from German to English. Why? Because more people use English in their everyday conversation and some of the usage of qatesttool scripts is confusing in German (some of the translations using Babelfish are humorous or confusing.) This will also allow others to contribute to this project without feeling pressured to learn German. James McKenzie -----Original Message----- >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] > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
