> From: Marcus Lindblom > Hi Toni, > > I agree that important classes (i.e. 'Node') and exceptional cases > should be documented. But as long as we are mostly developers, my > opinion is that adding fine-grit documentation is something of a waste > of good development time.
Developers of OpenSG, or developers of software that uses OpenSG? If the former, fine, but if the latter... how is anyone supposed to learn the system? > For NodePtr getChild(index), it's pretty obvious that you get a null ptr > if the index is out of range, since that is common engineering practise. > (If getChild returned a reference, then you'd need some documentation > saying if an exception gets thrown or whatever.) Is it obvious though? For a new user to OpenSG, there's a very real chance of checking the returned pointer against NULL, not NullFC... From my own experiences of learning OpenSG (and getting a very sore head from hitting it against the desk) I strongly recommend that everything is documented if the system is to ever reach a critical mass. This documentation process needs to be done by those who understand exactly how it works, i.e. the person who wrote it. Getting a third-party to document will just result in misleading info everywhere. It's also worth mentioning that there are also inconsistencies in the documentation that does exist! > Documenting everything, while being a honorable goal and useful for > adopting people fast, takes a lot of time to do, Agreed, a very long time. But it's the one thing that makes writing code that uses APIs an enjoyable task. I don't enjoy coding pain. > On good doc-api-examples, someone mentioned to me that Coin3D has pretty > good doxygen documentation. I think they also put most of the doxygen > stuff in the .cpp-files, but I haven't looked at it. > > /Marcus Phil ------------------------------------------------------------------------- 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
