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