Hi All,
Tiago was here for the last two days, and one of his main problems
(which is probably shared by may of you) was the accessibility of the
documentation. Doxygen is a good tool in general, but it doesn't fit the
OpenSG source structure all that well.
These are the main problems that I see:
- Clutter/Internal Classes
- typedef templates
- ...Base classes
Clutter/internal classes: It is just that the class hierarchy is
overloaded with classes that are not really useful for the end user,
like the Base classes, and a lot of the structure classes that are only
used internally. Gerrit has a doxygen patch to avoid this, but I think
the chances of getting this into the actual doxygen tree are small.
Typedef templates: we have a fair number of core classes that are not
really classes, they are just typedef specialization of templated base
classes (e.g. all the vectors). Doxygen doesn't show global typedefs at
all, so somebody looking for Vec3f is lost. In one I wrote a script that
created dummy classes just for doxygen, but it was a hack and gave an
impression of the code that was just not true.
...Base classes: As you know we split all FCs into Base and Derived
classes, where the base classes are auto-generated from the fcd files.
The problem is that this way the Derived classes (which are the ones hte
user sees) don't have the Base class data, primarily the Field
variables, so they seem to be pretty empty. The only thing doxygen can
do to get around this is to show all inherited members and methods. But
given that FCs have a whole bunch of generic functions, the full list
gets pretty cluttered, and not all that useful in and of itself.
Do you see other problems with the documentation? Please let us know
now, as this is the time to try to fix it.
As for how to fix it: One way is to try to hack doxygen to do more
sensible things with OpenSG. Gerrit has done some of it, and I tried
too, but the doxygen codebase is not easy to understand nor extend. It's
really not designed as much as grown, and it shows. So while it's
possible, it's difficult, and given that our requirements are pretty
OpenSG-specific I think the chances of getting patches into the doxygen
tree are pretty small, which means a anybody wanting to regenerate the
docs has to use a patched doxygen. Not a good situation, IMHO.
The alternative that Tiago proposed is to use doxygen as a
scanner/parser for C++ and instead of using its HTML output use the XML
output and generate the HTML ourselves. That way we can define what
needs to go where and get better control over how and what to include.
This idea came up yesterday evening, so we haven't had time to look into
the XML output to see if it's feasible, but I wanted to get some
feedback on it before we spend a lot of time.
The main question with this approach is what we need to include in the
documentation to avoid rewriting all of doxygen (which is a lot). So my
question would be which parts of the doxygen docs do you actually use?
Class hierarchy? File List? Directory List? Source Code? Related Pages?
Everything? :) We would also lose the other outputs like Latex, but I
don't think it's very useful at this point anyway.
The main goal would be to have useful documentation for users, not so
much for developers (they are tough enough to use doxygen ;). Something
along the lines of instantReality's documentation (see
http://www.instantreality.org/documentation/nodetype/IndexedFaceSet/ for
an example).
Another interesting addition (orthogonal to the other stuff) would be to
have a lot more Simple Examples that show how to use all the different
classes. We have some, but it would be good to get more, hopefully from
the community. More on that later.
What do you think? Makes sense? Insane? What parts of the documentation
do you really use, especially for somebody who's trying to get the hang
of OpenSG?
Yours
Dirk
------------------------------------------------------------------------------
Apps built with the Adobe(R) Flex(R) framework and Flex Builder(TM) are
powering Web 2.0 with engaging, cross-platform capabilities. Quickly and
easily build your RIAs with Flex Builder, the Eclipse(TM)based development
software that enables intelligent coding and step-through debugging.
Download the free 60 day trial. http://p.sf.net/sfu/www-adobe-com
_______________________________________________
Opensg-users mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/opensg-users
