[Mesa-dev] Documentation plan: request for comments

[Rogovin, Kevin]

Hello all,

  My current goal is to add documentation to Mesa so that the ramp up time of Mesa goes down a great deal. 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.

 -Kevin