[Mesa-dev] Documentation plan: request for comments

[Chad Versace]

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, 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

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.