[Mesa-dev] Documentation patch

[Rogovin, Kevin]

Hello all,

  Attached is a patch for doxygen documentation for developers (in particular new developers trying to ramp up) for Mesa. The documentation added is to function as an index tabled keyed by GL functionality.

  The contents of the patch are as follows:

  1.   The .doxy files (except for common.doxy and those related to gallium) found in doxygen/ are removed. Makefile and doxy.bat are updated
  2.  new doxygen file, all.doxy that generates a source browser tree for new people (like me) to quickly navigate the sources
  3.  text to give a quick and short overview for src/mesa/main and src/mesa/vbo. The contents of the overview for main are organized by chapter heading in the OpenGL 4.4 specification. These texts are located in doxygen/doxy_text. I have not poked into gallium at all.
  4.  the \mainpage tags found in various files of src/ are moved to files in doxygen/doxy_text
  5.  To use/see the documentation, do "make" in doxygen and use a browser on all/index.html

The documentation is meant as a developer reference, it has the sources inlined and cross-referenced. The upshot being that it takes some time for doxygen to generate the documentation (for my laptop about 90 seconds) Various IDE's and add-ons for editors give equivalent functionality but I have found browsing the sources this way quite effective here and in previous projects with large amounts of source code. The main content added by this patch is the index-text by subject and some text about the dispatch tables stored in gl_context.


I would greatly appreciate feedback, in particular the following

  1.  Accuracy of text
  2.  Suggestions for additions

Do people think it would also be a good idea to add in addition to what file features are mostly implemented to also add what key data structures and fields of data structures?


Additionally, I really, really, want the text in doxygen/doxy_text to eventually land in src/  and a policy put in place that as patches are added the corresponding doxy_text files are updated to reflect the patch. This will keep the documentation up to date and useful for new developers to ramp up more quickly. I am quite *new*, but as a newbie I can see the pain of a newbie. Before placing it in src/, I want to make sure that which is written is both useful and accurate.


Because of the size of the patch (98KB) I've attached the patch rather than in-lining it into the e-mail.



Best Regards,

 -Kevin
-------------- next part --------------
A non-text attachment was scrubbed...
Name: documentation.diff
Type: text/x-patch
Size: 100176 bytes
Desc: documentation.diff
URL: <http://lists.freedesktop.org/archives/mesa-dev/attachments/20131004/964fd652/attachment-0001.bin>