Did we ever finalize on a documentation standard? The wiki page about it seems to still be in a state of flux. (see: http://opensg.vrsource.org/trac/wiki/Dev/CodingStandard )
I would like to start documenting things that I reverse-engineer, but I want to make sure I do it right. :) -Allen Dirk Reiners wrote: > Hi Allen, > >On Tue, 2006-08-29 at 13:54 -0500, Allen Bierbaum wrote: > > >>Sounds a little like a chicken and the egg problem. You want the source >>files clean so when a developer goes there that already knows what they >>want they can get to it quickly. But at the same time you want good >>documentation that is up-to-date so users don't need to look at the >>source. >> >> > >I think the only thing we're really disagreeing is the class docu, which >I think is not big a deal (I just don't want it in the header ;). > > > >>I think the key choice to make here, is what is more important. Having >>good up-to-date documentation for users or having clean source files for >>developers. (personally I find well documented source files to be more >>useful as a developer as well, but maybe I am odd. :) >> >> > >The documentation will be there, just in a different place. ;) > > > >>Agreed on the methods. Put the documentation wherever the >>implementation is. Note, that for templates this means they would be in >>the header files with the methods. It also means that .inl >>implementations would have documentation in the "header" file as well. >> >> > >.inl doesn't count as header for me. > > > >>So... what is the outcome here? Are you willing to consider putting the >>member variable documentation with the member variables in the header file? >> >> > >I'm ok with that. > > > > >>I think we need to clarify something here. I see the programs in the >>source tree breaking down similar to this: >> >>- tutorials: Simple programming examples that have very little code and >>are helpful for learning >> ex: 10loading.cpp >> >> > >I see two versions of this. Tutorials, which are very extensively >documented, and examples, which are small and just show how to do things >with minimal or no documentation. > > > >>- tests: Unit tests or very obtuse pieces of code to excersize specific >>functionality >> ex: geomtry_unit_test >> >> > >Yes, and these should be integrated into some framework. The main >difference to examples is that they need scaffolding to automatically >test outcomes. > > > >>- examples: Potentially involved examples of how to use various aspects >>of OpenSG. >> ex: ShadowMapping, billion polygon renderer, osgSceneViewer >> >> > >I'd see a split between those. ShadowMapping and billion polygon >renderer are just examples. They don't need alot of code, you just set >it up and it runs. Cluster and Window stuff needs a little more setup >than other things, so either we make a different example wrapper, or use >the non-wrapped version. > >osgSceneViewer is a different story. That's a real application that has >functionality (and code) beyond just showing one thing. Similar things >are true for apps that are not in the source tree per se (like the >ARToolkit example or other GUI toolkit examples). I'm not sure where to >put those, maybe an apps directory? > >Another not-very-clear thing are helper programs like the proxy builder >or the osgConv. Those are somewhere in the middle. > > > >>In my book, example doesn't have to mean simple or small. It is meant >>to be an example of how to do something, not a tutorial about how to >>learn something. That said, I am sure there will be some examples that >>are very simple and just demonstrate some small functionality but one >>thing OpenSG is really missing that examples can help with is full >>examples of complex capabilities. An example of how to use >>cluster-based rendering is something we need an example of, but it is >>definitely not going to fit into something smaller then the SSM. >> >> > >It would, if there was away to specify the Window to use. > > > >>It may >>not even use the SSM because it needs a more complex scene manager. >> >> > >Hm, nope. The cluster tutorials use the SSM. ;) > > > >>I am all for using something very simple for tutorials, but we need full >>examples. I want people to see the power of OpenSG to do advanced things. >> >> > >Advanced and simple doesn't exclude each other. I would like to show how >simple it is to do advanced things in OpenSG, and how to do real >applications with it, too. > > > >>I will try to get it setup in the next couple of days. >> >> > >Thanks! > > 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 > > > ------------------------------------------------------------------------- Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT & business topics through brief surveys -- and earn cash http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV _______________________________________________ Opensg-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/opensg-users
