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