Marcus Lindblom wrote: >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. > > I understand this sentiment, but I have to agree with another poster that said the goal of the software is to be used and to be used it needs to be documented. I think the key is to find a process by which (documentation != developer.pain)
>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.) > >Unless someone is willing to do it, or willing to pay some one else to >do it, I think all that is needed is to put a little something on every >class and try to document non-obvious things. That would give us much >improvement with relatively little effort. > > I agree in principle. I would change this to be put a lot of something on the classes that users should actually use directly. (Node, Cores, States, etc) >Documenting everything, while being a honorable goal and useful for >adopting people fast, takes a lot of time to do, not to mention keeping >all that updated (which is the really difficult part). And when >documentation and code start to disagree, you'll find yourself happier >with no documentation rather than confusing documentation. :) > >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. > > In my mind these last two are related. Documentation has to be kept up to date, so we need a documentation method that leads to developers keeping it up to date. To paraphase Kent Beck of XP-development fame, keep everything close to the code because the code is the "real" documentation. What I have found useful for this is to put the documentation near the thing being documented that the developer is/maybe changing. So for example, put the documentation for member variables next to the member variable declaration. If the variable changes, the documentation is right there in the developer's face to be changed. Similarly, put the documentation for a method as the header to that methods definition (whever it is wether that be .cpp/.h/.inl). Once again the point is to keep the documentation right in front of the developer so it is kept up-to-date. -Allen >/Marcus > >Antonio Bleile wrote: > > >>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 >> >> >> > > >------------------------------------------------------------------------- >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
