[Mesa-dev] More questions from a newbie

[Rogovin, Kevin]

 Hi all,

>I'm not aware of any public web servers that serve up the doxygen documentation right now.  If you can find one (or set up one, or convince the freedesktop.org<http://freedesktop.org> >maintainers to set up one), I would be in favor of putting overview style documentation in doxygen format.  Otherwise I think it would be better to add overview style >documentation to the existing docs/ directory in html form, because that's what people see if they go to http://www.mesa3d.org/.

There is a link to the doxygen magicks, over at "Developer Topics -> Source Code" and then a link as the last word in the text " .. documentation here". The link is dead; however, the link to bufferobj.c works.

I really think the docs should be "part of the source code" to help guarantee they do not rot; who would I contact of http://www.mesa3d.org so that the link to the source code would work? It will mean that whoever maintains the site will need to run #cd doxygen && make, which I hope would not be a big deal.

>If we can find or set up a public server serving up the latest doxygen documentation (and that's a big "if"), then I'd be in favor of adding group tags so that module >categorization is in the sources.  But I don't understand the benefit of having two separate doxygen outputs (one for headers and one for all code).  The fact is, the only >consumers of the doxygen output are going to be mesa developers and people who are interested in understanding the source code.  That argues for one piece of >doxygen output that contains all the code.  Besides, we currently have zero public doxygen builds of Mesa; I'd far prefer to take the incremental step of changing this >to one, and seeing how it goes for a while, rather than jumping to two and risking confusing people.

I agree with you, two doxygen runs is silly since Mesa is an implementation of documented and speced API; thus the only doxygen documentation would include sources that are linked so that a developer can quickly navigate. As for the how, this is what I am thinking of doing:

1.       First just tweak the .doxy files found in doxygen (they have that various directories are processed by doxygen separately so that the module thing is kind of done by directory already). However, write the overview text (new files) in each of the main directories. The text would be in a \mainpage header. Since each directory is a separate run, it will then present the overview text of that directory when clicked. If a directory already has a main page then just edit that.

2.       Once the documents look good and people are happy with AND there is update from the websites to make and host the doxygen stuff, then redo the doxygen files a bit to one doxygen file and then add group tags to the headers.

The 2nd step is not really needed if people are happy with the results of (1)... and skipping (2) has one positive side-effect, one can then, if one chooses, organize the sources into sub-groups of a main directory. Given that step 1 is not even started, I think figure out 2 if 1 gets done as needed.

>There's a lot of code in core Mesa that is shared by all drivers.  Even if your documentation efforts only wind up affecting i965 code and shared code, they will still >benefit everyone.  I think the best way to address this is to take the "patches welcome" attitude--if you set up a public doxygen server, and get the documentation into >good enough shape that it is useful, either the gallium folks will want to contribute (in which case they can, by updating comments in the gallium code), or they won't >(in which case they still will benefit from the doxygen documentation in core Mesa).  Either way it's a win.

I'll try to get something set up; but to make progress faster and now, I'll start reading and then writing those \mainpage texts for each main directory. I'll start posting the text here once I've written something that has some info it. Along those lines, which is preferred by those doing the reading and checking posting the text as a patch or just the text itself?

Best Regards
-Kevin

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/mesa-dev/attachments/20130920/26916d7a/attachment-0001.html>