Dirk Reiners wrote: > Hi Simon, > >On Wed, 2006-08-23 at 09:22 +0200, Simon Haegler wrote: > > >>micro-comments concering doxygen: >> >> >> [snip]
>>(2) i completely agree that most of the param-names stand for themselves and >>that we don't need the "setX() sets variable X" type of docs. >> >> > >Thank you! ;) > > As a user, I must step in and say that I completely disagree. ;) Yes, the param names can tell you they mean something but there needs to be documentation about how to interpret their usage. An example of one that caught me. The DistanceLOD group node. It has two parameters dutifully documented as: sfCenter: The center for distance calculation mfRange: The range values. When I first saw this though I had no idea what this actually means in usage. I had to submit a patch that added documentation about how to really use the ranges and in what coordinate system the center point is. To figure all this out I had to look at the test and the code to reverse engineer how the thing works. I would never suggest that *every* method needs to be documented. But I think every derived class type should be documented to describe a) what it is and b) how to use it. (preferably with a code example or a link to one). Additionally I think the majority of the fields should be documented with a) what it is used for and b) allowed values or a link to where you can find allowed values. For example in the State code there are many fields that need to be filled with a value from OpenGL (example: sfInternalFormat). For people without a very good understanding of OpenGL they don't know where to go to find the valid values. Another example, sfPriority. The docs say it is a priority for a texture, but how and when is it used. I don't need a book written for everything, but as a user, I would really like enough documentation in the reference guide to make it useful for me to understand what the classes, methods, and fields are for. Right now to do this I have to generate the doxygen documentation with the source code inline so I can look at the code to figure out how to use the system. IMHO, this is not a good thing. But I could be wrong... :) -Allen > 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 > > > ------------------------------------------------------------------------- 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
