Dirk Reiners wrote: > 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 > >/*! > >*/ > > My counter argument to this is that the reason I use javadoc style documentation blocks (ie. /** ... */ and @param, @return, etc) is that some of the editors I use support that format and understand it. I don't know any that understand the alternative doxygen syntax. If having tools support for comment blocks is at all desirable javadoc style is probably the way to go. It also allows people that already code in java to transfer their knowledge a little easier.
>- 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. > > This is really the only thing in the standard that I significantly disagree about. Many times in the discussion thread we have talked about how it is important to keep the documentation in sync. As I think many of us have said, a great way to do this is to keep the documentation in the developers face and placing the documentation as close to the thing being documented as possible. So I still thinking putting documentation for members in the header files is the best policy. (I would make the same argument for putting the documentation for the class in the class header but with the additional reason that if a user is trying to read through header files to understand/find classes it is very helpful to have the description of the class actually with the class.) Why are you so opposed to putting documentation in the header files? >- 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. > > Agreed. >- 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. > > I would modify this rule with "if it is one or two clicks away and obvious that you can click to find it". >- 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. > > I will take a look. -Allen >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 >Opensg-users@lists.sourceforge.net >https://lists.sourceforge.net/lists/listinfo/opensg-users > > > ------------------------------------------------------------------------- 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 Opensg-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/opensg-users
