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
Opensg-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/opensg-users
