On Tue, Oct 08, 2013 at 09:00:33AM +0300, Kevin Rogovin wrote: > --- > doxygen/all.doxy | 1 + > src/gbm/gbm.doxy_text | 15 ++ > src/mesa/drivers/dri/i965/i965.doxy_text | 176 +++++++++++++++++++++ > src/mesa/main/main.doxy_text | 257 > +++++++++++++++++++++++++++++++ > src/mesa/program/program.doxy_text | 33 ++++ > src/mesa/swrast/swrast.doxy_text | 42 +++++ > src/mesa/tnl/tnl.doxy_text | 33 ++++ > src/mesa/vbo/vbo.doxy_text | 158 +++++++++++++++++++ > 8 files changed, 715 insertions(+) > create mode 100644 src/gbm/gbm.doxy_text > create mode 100644 src/mesa/drivers/dri/i965/i965.doxy_text > create mode 100644 src/mesa/main/main.doxy_text > create mode 100644 src/mesa/program/program.doxy_text > create mode 100644 src/mesa/swrast/swrast.doxy_text > create mode 100644 src/mesa/tnl/tnl.doxy_text > create mode 100644 src/mesa/vbo/vbo.doxy_text > > diff --git a/doxygen/all.doxy b/doxygen/all.doxy > index 46a00de..e86fe00 100644 > --- a/doxygen/all.doxy > +++ b/doxygen/all.doxy > @@ -37,6 +37,7 @@ INPUT = ../src/mesa/main/ \ > ../src/mesa/drivers/dri/i965 \ > ../src/glx/ \ > ../src/glsl/ \ > + ../src/gbm \ > ../src/gbm/main \ > ../src/gbm/backends/dri/ \ > ../src/egl/ \ > diff --git a/src/gbm/gbm.doxy_text b/src/gbm/gbm.doxy_text > new file mode 100644 > index 0000000..3730549 > --- /dev/null > +++ b/src/gbm/gbm.doxy_text > @@ -0,0 +1,15 @@ > +/** > + * \page GBM The Generic Buffer Manager > + * > + * This module provides an abstraction that the caller can use to request a > + * buffer from the underlying memory management system for the platform. > + * > + * This allows the creation of portable code whilst still allowing access to > + * the underlying memory manager. > + */
I see a few problems with the approach. First, patch two in the series removed the very stuff: diff --git a/src/gbm/main/gbm.h b/src/gbm/main/gbm.h index 9d2a030..ee4bd75 100644 --- a/src/gbm/main/gbm.h +++ b/src/gbm/main/gbm.h @@ -46,15 +46,7 @@ struct gbm_device; struct gbm_bo; struct gbm_surface; -/** - * \mainpage The Generic Buffer Manager - * - * This module provides an abstraction that the caller can use to request a - * buffer from the underlying memory management system for the platform. - * - * This allows the creation of portable code whilst still allowing access to - * the underlying memory manager. - */ + 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). 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. 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? -Topi _______________________________________________ mesa-dev mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/mesa-dev
