[Mesa-dev] Documentation plan: request for comments

[Chad Versace]

On 10/18/2013 01:43 PM, Paul Berry wrote:
> On 11 October 2013 14:40, Chad Versace <chad.versace at linux.intel.com <mailto:chad.versace at linux.intel.com>> 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.