[Mesa-dev] [PATCH 3/3] doxy-text files added

[Rogovin, Kevin]

> If patch two was applied and this (patch three) wasn't, then mesa would contain
> less documentation than before. Idea is that every commit on its own makes
> things better and never worse. Hence the addition in this patch (number three)
> would need to go together with the removal done in patch two. (The same applies
>of course for the other six new files addressed in this patch).

 You are correct; I broke down the patches by function rather than immediate utility.

> Second, each patch should address one thing at a time. Hence each switch of
> documentation from one file to another should be submitted as its own commit.
> All the new documentation text in turn should be separated into its own commits
> in order to reviewers distinguish easily what is old text and what is new. It is
> too much to ask for people to start checking existing and comparing manually.

 This I can do, but I am going to hold off on this until I get some feedback on
the pros and cons of having a single file providing the index or not.

> Third, there should be rational why the change is needed. Here it is not
> obvious what is the benefit of moving the documentation away from source code
> to doxy-files. Is this perhaps preparing for something that cannot be achieved
> if the documentation remains in the source code?

I've sent out a RFQ about how to document Mesa (after you wrote this e-mail, but before
I read yours). The main goal of the documentation is to provide an overview of Mesa. 
The current situation of Mesa is that elements are reasonably well documented on a
local level but there is very little about how different parts work together. That lack 
makes the following difficult:
  - Improvement of an area (optimizations in particular) based upon benchmark performance
  - Debugging incorrect interaction behavior
  - Additional features that interact with current GL implementation.

Without an index and/or interaction guide, it is quite time consuming to address any of 
these questions. In theory, a -new- developers (who is also quite capable) should be
able to quickly know what data structures and functions are responsible for implementation
of a feature and atleast a list of what functions and data structures interactions might take
place. All we have right now for seeing where/how a function or structure are used and
when is grep and naming conventions. This gets quite tricky as Mesa (and even more so for i965) 
have large  function tables whose contents are set at run time, making static analysis an iffy affair
at best. At this time getting started with Mesa is a vertical cliff that will stop potentially useful
contributions, and for that matter a great deal harder to tell at a glance side effects of patches
to existing functions.

In order for Mesa implementation to progress, I think it requires the ability for new,
competent developers to be able to get up to speed quickly. The idea that only
work on one little corner and hope for the best is going to get harder and harder as
optimization and not feature set become more important and more interconnected.

The .doxy_text files of the patch attempt to give an organization by function for
each source file so that a new developer can quickly (ideally) know where something
is implemented. In addition the first patch changes the doxgen run so that cross
referencing (in particular knowing what functions call a given function) is reliable
across modules. The inline sourcing of an browser for some can be a much quicker
way to navigate and see (but not edit) blocks of source. Additionally, the old .doxy files
generated data very unorganized, especially with respect to data structures. For main,
it generated too much too flatly to the point it was not obvious what data structures
are the major players and what are minor players; worse since it did not inline the sources
one could not see what was called by what and how functions interacted. 

One can make a case that the categorization of the files should be done within a file,
the main issue here is the tool doxygen. This question is addressed in my other e-mail
to the mailing list. 

-Kevin