On 8/29/06, Dirk Reiners <[EMAIL PROTECTED]> wrote: > > Hi all, >
Hi, [snip] > > - I've thought about the best place to document the member vars. They > don't have a natural representation in the source file, so it's either > an unnatural one, or the header. I picked the beginning of the .cpp > file. > Why not use the header file? To have the definintion and documentation of member vars in different files makes it harder to hold them in sync (remember to document new vars and to remove the documentation of removed ones). This can lead to inconsistent documentation. > - I'm unsure about documentation for basic concepts (like the bounding > volume). I would like those to be in the Wiki, to simplify editing them, > but that makes inclusion into doxygen very hard (linking to and from the > doxygen docs). Losing the nice integration of textual and source > documentation would be IMHO a noticeable loss. So my current thinking is > to keep the current method of using doxygen Related Pages for general > documentation and concepts. Edits would have to be patches against svn, > handled just like the code doc changes. > It is also possible to use the doxygen "\copydoc" command to merge the documentation of related pages into one page (the main page?). (I know the question was asked before, but I didn't come to answer it before, sorry ;) ) > - Just some taste questions: use 'see also' sections or integrate links > into the text as far as possible (see getSFCore vs. getMFChildren). > Related to that: few or many links (e.g. changed())? > We seem to have the same taste regarding documentation ;) I think this is a MUST and doxygen makes it easy to add links (sometimes too easy, i.e. too many links to the Node documentation in Dirk's version, only because the word Node is very common)! > - I just documented everything. In the full system I wouldn't document > methods that are reimplemented from parent classes. Doxygen allows you > to repeat reimplemented documentation, but I wouldn't do it. One click > is acceptably close, IMHO. > > > - I think one of my informal rules would be: if it is one or two clicks > away, don't repeat it (e.g. docs for reimplemented classes, docs/links > for concepts are explained/linked elsewhere). I think it's not too much > of a burden to click on a link to find a link to the explanation. > According to that rule I wouldn't have the Multi-Thread Safety link in > changed(), because it can be found in beginEditCP(). I might be a little > more lenient with links (i.e. repeating direct links to the related page > would be ok), but I would like to avoid repeating actual text as far as > possible, to simplify changes. > Here also we could use "\copydoc" to copy documentation of other members, functions etc. For example take the Node's destructor in Dirk's documentation: it's general enough to be used for all field containers. It can also be used to extend the documentation of inherited members without having to rewrite everything. > - Do we want \brief comments for methods and member variables? IMHO no, > all they do is safe a click to the same page (i.e. fast), and they add > clutter to the method list at the beginning of the page, which is > already too long for my taste. We might want to think about reducing the > number of groups in general... > > - I did add \post comments for non-trivial methods (e.g. > replaceChildBy). I strongly object to adding them to trivial ones, > though (e.g. setTravMask). > > I wrote a style/doc guide proposal, based on our old style guide from > the SF Wiki, it's at > http://opensg.vrsource.org/trac/wiki/Dev/CodingStandard for now. > Comments welcome. > > Yours > > Dirk > Bye, -- Haykel BEN JEMIA http://www.haytec-tn.com ------------------------------------------------------------------------- Using Tomcat but need to do more? Need to support web services, security? Get stuff done quickly with pre-integrated technology to make your job easier Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642 _______________________________________________ Opensg-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/opensg-users
