Hi all,
ok, here's my version, and my comments to the other versions. I also put
them up at www.dirkreiners.com/doc_challenge , to compare the results.
To create those I turned the INLINE_SOURCES, REFERENCED_BY_RELATION and
REFERENCES_RELATION options off compared to the current CVS ones. I also
only created the page for Node, so none of the external links will work.
I based my style on the existing code style and just extended it for
documentation.
Comments to Carsten's and Allen's style:
- I don't like the
/**
*
*/
style very much, as it's hard to edit once it's written. If using a
syntax-highlighting editor, block comments are pretty easy to spot, so
IMHO the '*'-eye candy is not really necessary. I'd go simply for
/*!
*/
- 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.
- 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.
- 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())?
- 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.
- 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
-------------------------------------------------------------------------
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
