HI Bram,
On 31 August 2014 15:11, Bram Vaessen <[email protected]> wrote: > Hi Björn, > > My idea is actually closely related with your point 2: the in depth > documentation of OSG. As far as I know however, doxygen is generated from > the comments in the source code, so everyone who wants to add or say > something about any function would have to do it in the source code (please > correct me if I'm wrong), which doesn't seem ideal to me. > > Also the doxygen seems to list absolutely everything and makes no > distinction between functions/classes that are meant to be used by the user > of OSG, and classes and functions that are more private and used inside > OSG, and I think this is detrimental to understanding OSG from it. > > In my ideal view of the OSG documentation (besides good examples and > tutorials), it would include an API documentation where it's clear what > classes and functions are part of the interface of OSG and how you can use > them. > Which methods of classes and what classes are of interest to users varies from user to user, a power user may well want to subclass and override methods that other users would rather treat as internal implementation details. This means it's actually pretty rare one could strickly assign certain methods in classes, or certain classes of no interest to user and unnecessary to list in documentation. So the level of granularity that our current doxygen docs provide might be too fine grained for a new user, but as time goes on they may well more and more of the less used methods/classes exposed. As a general note, I'd add that we have had two previous wiki based websites with the hope that it'd make it easy for the community to contribute and help document but it largely failed to garner widespread contributions from the community, it was really just the core developers/web admins that actually made meaningful contributions and it's tended to be sporadic activity with little bursts when certain topics came up. A sustained documentation effort isn't easy to maintain just from peoples spare time. Robert.
_______________________________________________ osg-users mailing list [email protected] http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
