On 11 October 2013 14:40, Chad Versace <[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?
_______________________________________________ mesa-dev mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/mesa-dev
