Hi, > I've heard the cry for a parameter-by-parameter documentation a number > of times, and I have a hard time subscribing to it. I think most of > our methods are self-explanatory just by the parameter names. If you > could give me examples where you couldn't get to understand what the > function/method does without documentation I'd be interested. What I
OK, as an example, take the "Node" class. Do you see _any_ documentation on that? Isn't this class quite important? Take the two methods: DynamicVolume & osg::Node::getVolume ( bool update ); void Node::getWorldVolume( DynamicVolume &result); So you say, the name of the method says it all. OK, so my guess is that those methods return a volume. Of what? And what's the exact difference of the two methods? And what's a DynamicVolume anyway? What does the parameter "bool update" mean? When should I use true/false and why? Come on, don't tell me that this is "self-explanatory". And simple methods like NodePtr osg::Node::getChild( UInt32 childIndex ) need a proper documentation! I mean, I don't expect that you tell me what childIndex means, but I want to know what is returned if I give you an inexistent childIndex. I agree though that set/get methods which set and return a member variable don't necessarily need a documentation. The doc seems to be inconsistent also, in some classes you find it with the prototypes, sometimes you have to go to the implementation in order to see the doc. > think would make more sense, and I have spent some time on it, is a > conceptual level documentation that explains the concepts and the > goals, and actually most of the parameters in the form of the related > pages in the doxygen docs. Most of those should be linked from the > class reference page and be easily accessible. Are those useful and > used? If not, why not? What's missing? What are you talking about? > I'm not a big fan of documentation that explains me that the parameter > 'child' of the method 'addChild' is the child that is added. We also You can write: "Adds 'child' as child of this Node, if child is Null blabla... else blabla, returns true on success, otherwise returns false". > have a ton of auto-generated code, and having docs that say 'setBla() > sets the bla value' is not very helpful. I don't want to read that, > and I certainly don't want to write it. I'm not a big fan of having > the docs inside the headers, as many of our headers are already pretty > long, and I agree. But you can configure doxygen to take the doc of the method from the cpp files, so you get clean headers and all the doc in the implementation part. > adding a slew of docs won't help with that. Do you have good examples > for this kind of documentation? > I would also be interested in good examples for documentation in > general (finding bad ones is easy ;), so if you have a system that is > exceptionally well documented, please send me a link. I took a quick Take QT. It's the best documented API I've ever seen. I admit that they put a lot of effort into it, and I'm well aware that OpenSG can't get to those levels. But it's a good reference... QT uses good member names too, and they even do document the most intuitive of them anyway, like: " bool QImage::isNull () const Returns true if it is a null image, otherwise returns false. A null image has all parameters set to zero and no allocated data. " or in the same class: " int QImage::height () const Returns the height of the image. " You can either like it or not, I personally like it. There's a lways something you can say about the most stupid set/get method, e.g. how it behaves in exceptional cases etc... > Gerrit mentioned the documentation build times: those are a serious > problem. Doxygen takes longer than compiling the whole system (twice) > plus examples. For developing I turn off everything except the piece I'm > working on, and that's bearable, but not a good solution. I've tried The doc does not have to be up to date in real time I think, so you might consider generating it just once a week or so. Regards, Toni ---------------------------------------------------------------- This message was sent using IMP, the Internet Messaging Program. ------------------------------------------------------------------------- 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
