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

[Pohjolainen, Topi]

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