On 10/18/2013 01:43 PM, Paul Berry wrote:
On 11 October 2013 14:40, Chad Versace <[email protected] <mailto:[email protected]>> wrote:On 10/10/2013 01:38 AM, Rogovin, Kevin wrote: Hello all, My current goal is to add documentation to Mesa so that the ramp up time of Mesa goes down a great deal. I support that goal. When I see other projects that publish good Doxygen documentation, like http://llvm.org/doxygen/__modules.html <http://llvm.org/doxygen/modules.html>, I become jealous and wish Mesa did the same. In addition I wish to create an index of files and data structures keyed by subjects. The use case of such an index is of the form "How does Mesa does functionality foo? Where are those functions and states?" and then one can quickly find the files and data structures to answer that question. The goal I have is that one can use doxygen output to quickly browse source code to find the implementation details as well. There are several approaches that I can think of on how to accomplish this, so far I have come up with 2 options: Option A: A separate file that lists an organization of files of Mesa by functionality. Each file is placed into a section and/or subsection and a brief description of each file. This I have already done. Advantages: easier to organize text, easier to create linking narration between groups. Greater control over text presentation to create a flow, especially between units. Disadvantages: Document needs to be maintained as a separate file: as files are added and changed they need to update their entries in the file. OR Option B: A set of doxygen groups and subgroups. The groups and subgroups will have names given by functionality. Each header AND _source_ file would be placed into a group. In addition each source file would have a file tag describing what it does. This requires adding the necessary doxygen tag header "\addtogroup FOO @{" and footer "@}". For those files that provide support to another file, those files should be in a list stating that they support another file. Advantages: Documentation is better localized to a file. Changes to a file will then get their documentation updated too with the file. Disadvantages: Very difficult to make a good table of contents without resorting to a script to run on the files hunting for tags (AFAIK doxygen does not generate nice TOC's for groups). Massive number of patches for the first commit since it would essentially touch every file. Trickier to create linking narration for different groups. Option A is already done for src/mesa/main and src/mesa/vbo. Thoughts, suggestions, etc are greatly appreciated. I prefer option B, keep the documentation as close to the source as possible. Mesa developers, according to my observations, do not fastidiously maintain documentation. So I believe you will need to eliminate as much maintenance overhead as possible, and put the docs close to the source, if you intend to succeed at your endeavor. To aid everyone in examining the current state of our Doxygen, I've automated it publication every 4 hours to here: http://people.freedesktop.org/__~chadversary/mesa/doxygen <http://people.freedesktop.org/~chadversary/mesa/doxygen> I'm currently building the Doxygen only for master. If you'd like me to automate publication of one your branches too, just let me know. Any chance we could move this to a non-Chad-specific section of the web site, and put a link to it on the main Mesa page?
Paul, I just CC'd you on a new thread regarding that. _______________________________________________ mesa-dev mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/mesa-dev
