[Mesa-dev] Documentation plan: request for comments

[Paul Berry]

On 11 October 2013 14:40, Chad Versace <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?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/mesa-dev/attachments/20131018/7a40d9c8/attachment.html>