I like the way you are going about this talking about what we want the documentation to be before talking about what tool or method to use to generate it.
See below... On Sat, Mar 21, 2009 at 1:19 PM, Dirk Reiners <[email protected]> wrote: > > 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. Agreed. I like to see these for developer version of the docs, but they are not needed in general. > 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. Agreed. These just don't show up well in Doxygen and can confuse the heck out of people. > ...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. Agreed again. I also think this could be made much better by taking advantage of the details know in the .fcd files. For example the link you point to below shows all the fields, types, descriptions, etc. We have all that (or could) in the .fcd files, we just need to make better use of it. > Do you see other problems with the documentation? Please let us know > now, as this is the time to try to fix it. There are a couple areas I think could help. First off though let me point to the qt 4.5 documentation (http://doc.trolltech.com/4.5/index.html). I think this is the best example of documentation I have seen for a software project and there is a lot that can be learned. Cross referenced examples: I think it would be great to have example pages that have a mixture of the code from the actual application (the exact code that is being compiled in the build) intermixed with tutorial style information. For example: http://doc.trolltech.com/4.5/graphicsview-collidingmice.html This is very helpful to a new or existing user to see how to use something. Having it off live code that is used for testing and examples is even better because we make sure the code is always up to date. Annotated classes list: Something like this: http://doc.trolltech.com/4.5/annotated.html A common question I see with OpenSG is "what class can solve my problem". Many of the classes don't have anything that describes what they are for and there is no place I know of to just see a full list with short descriptions. This could help tremendously. Common starting point: Having a main starting point page similar to (http://doc.trolltech.com/4.5/index.html) that links to tutorials, class lists, etc would be extremely useful. So instead of treating the tutorials and examples and API documentation as separate items, the user could see them as a single thing ("the documentation") and use it to find what they need. The technology/feature overview pages are especially useful and could be based upon the existing tutorial code. That is my two cents. > 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. Two additional ideas here: - What about outputting the doxygen TAGFILES and postprocessing it before pulling it back into doxygen to generate the docs. - Filter the XML files as needed and then use XSLT-based generation like this example (http://dox.narechk.net/index_en.html). I don't really like this specific one, but we may be able to come up with something better. -Allen > 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 > ------------------------------------------------------------------------------ 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
