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
_______________________________________________
mesa-dev mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/mesa-dev
