[gimp] libgimpmath: move docs from template files to inline comments

[Michael Natterer <mitch src gnome org>]

commit 2ce4075eebe146aff4ea9f77faf80d408a2d64aa
Author: Michael Natterer <mitch gimp org>
Date:   Fri Jul 2 14:41:35 2010 +0200

    libgimpmath: move docs from template files to inline comments

 devel-docs/libgimpmath/.gitignore           |    1 +
 devel-docs/libgimpmath/tmpl/.gitignore      |    2 -
 devel-docs/libgimpmath/tmpl/gimpmath.sgml   |   78 -----
 devel-docs/libgimpmath/tmpl/gimpmatrix.sgml |  268 ---------------
 devel-docs/libgimpmath/tmpl/gimpmd5.sgml    |   29 --
 devel-docs/libgimpmath/tmpl/gimpvector.sgml |  482 ---------------------------
 libgimpmath/gimpmath.h                      |   63 +++-
 libgimpmath/gimpmatrix.c                    |   18 +
 libgimpmath/gimpmatrix.h                    |   18 +
 libgimpmath/gimpmd5.c                       |    9 +
 libgimpmath/gimpvector.c                    |   10 +
 libgimpmath/gimpvector.h                    |   24 ++
 12 files changed, 135 insertions(+), 867 deletions(-)
---
diff --git a/devel-docs/libgimpmath/.gitignore b/devel-docs/libgimpmath/.gitignore
index fbb7295..6bf1585 100644
--- a/devel-docs/libgimpmath/.gitignore
+++ b/devel-docs/libgimpmath/.gitignore
@@ -12,6 +12,7 @@
 /libgimpmath-undeclared.txt
 /libgimpmath-undocumented.txt
 /html
+/tmpl
 /xml
 /version
 /.libs
diff --git a/libgimpmath/gimpmath.h b/libgimpmath/gimpmath.h
index d9faa36..ac77dcc 100644
--- a/libgimpmath/gimpmath.h
+++ b/libgimpmath/gimpmath.h
@@ -39,31 +39,78 @@
 
 G_BEGIN_DECLS
 
-/* Some portability enhancing stuff. For use both by the gimp app
- * as well as plug-ins and modules.
+
+/**
+ * SECTION: gimpmath
+ * @title: GimpMath
+ * @short_description: Mathematical definitions and macros.
  *
- * Include this instead of just <math.h>.
- */
+ * Mathematical definitions and macros for use both by the GIMP
+ * application and plug-ins. These macros should be used rather than
+ * the ones from <math.h> for enhanced portability.
+ **/
+
 
-/* Use RINT() instead of rint() */
+/**
+ * RINT:
+ * @x: the value to be rounded
+ *
+ * This macro rounds its argument @x to an integer value in floating
+ * point format. Use RINT() instead of rint().
+ **/
 #ifdef HAVE_RINT
 #define RINT(x) rint(x)
 #else
 #define RINT(x) floor ((x) + 0.5)
 #endif
 
+/**
+ * ROUND:
+ * @x: the value to be rounded.
+ *
+ * This macro rounds its argument @x to the nearest integer.
+ **/
 #define ROUND(x) ((int) ((x) + 0.5))
 
-/* Square */
+/**
+ * SQR:
+ * @x: the value to be squared.
+ *
+ * This macro squares its argument @x.
+ **/
 #define SQR(x) ((x) * (x))
 
-/* Limit a (0->511) int to 255 */
+/**
+ * MAX255:
+ * @a: the value to be limited.
+ *
+ * This macro limits it argument @a, an (0-511) int, to 255.
+ **/
 #define MAX255(a)  ((a) | (((a) & 256) - (((a) & 256) >> 8)))
 
-/* Clamp a >>int32<<-range int between 0 and 255 inclusive */
+/**
+ * CLAMP0255:
+ * @a: the value to be clamped.
+ *
+ * This macro clamps its argument @a, an int32-range int, between 0
+ * and 255 inclusive.
+ **/
 #define CLAMP0255(a)  CLAMP(a,0,255)
 
+/**
+ * gimp_deg_to_rad:
+ * @angle: the angle to be converted.
+ *
+ * This macro converts its argument @angle from degree to radian.
+ **/
 #define gimp_deg_to_rad(angle) ((angle) * (2.0 * G_PI) / 360.0)
+
+/**
+ * gimp_rad_to_deg:
+ * @angle: the angle to be converted.
+ *
+ * This macro converts its argument @angle from radian to degree.
+ **/
 #define gimp_rad_to_deg(angle) ((angle) * 360.0 / (2.0 * G_PI))
 
 
diff --git a/libgimpmath/gimpmatrix.c b/libgimpmath/gimpmatrix.c
index 4114eaf..5d09a31 100644
--- a/libgimpmath/gimpmatrix.c
+++ b/libgimpmath/gimpmatrix.c
@@ -26,6 +26,24 @@
 #include "gimpmath.h"
 
 
+/**
+ * SECTION: gimpmatrix
+ * @title: GimpMatrix
+ * @short_description: Utilities to set up and manipulate 3x3
+ *                     transformation matrices.
+ * @see_also: #GimpVector2, #GimpVector3, #GimpVector4
+ *
+ * When doing image manipulation you will often need 3x3
+ * transformation matrices that define translation, rotation, scaling,
+ * shearing and arbitrary perspective transformations using a 3x3
+ * matrix. Here you'll find a set of utility functions to set up those
+ * matrices and to perform basic matrix manipulations and tests.
+ *
+ * Each matrix class has a 2 dimensional gdouble coeff member. The
+ * element for row r and column c of the matrix is coeff[r][c].
+ **/
+
+
 #define EPSILON 1e-6
 
 
diff --git a/libgimpmath/gimpmatrix.h b/libgimpmath/gimpmatrix.h
index 5919b66..c55646c 100644
--- a/libgimpmath/gimpmatrix.h
+++ b/libgimpmath/gimpmatrix.h
@@ -26,16 +26,34 @@ G_BEGIN_DECLS
 
 /* For information look into the C source or the html documentation */
 
+/**
+ * GimpMatrix2
+ * @coeff: the coefficients
+ *
+ * A two by two matrix.
+ **/
 struct _GimpMatrix2
 {
   gdouble coeff[2][2];
 };
 
+/**
+ * GimpMatrix3
+ * @coeff: the coefficients
+ *
+ * A three by three matrix.
+ **/
 struct _GimpMatrix3
 {
   gdouble coeff[3][3];
 };
 
+/**
+ * GimpMatrix4
+ * @coeff: the coefficients
+ *
+ * A four by four matrix.
+ **/
 struct _GimpMatrix4
 {
   gdouble coeff[4][4];
diff --git a/libgimpmath/gimpmd5.c b/libgimpmath/gimpmd5.c
index 911f14d..e314884 100644
--- a/libgimpmath/gimpmd5.c
+++ b/libgimpmath/gimpmd5.c
@@ -14,6 +14,15 @@
 
 
 /**
+ * SECTION: gimpmd5
+ * @title: GimpMD5
+ * @short_description: The MD5 message-digest algorithm
+ *
+ * The MD5 message-digest algorithm
+ **/
+
+
+/**
  * gimp_md5_get_digest:
  * @buffer:      byte buffer
  * @buffer_size: buffer size (in bytes) or -1 if @buffer is nul-terminated.
diff --git a/libgimpmath/gimpvector.c b/libgimpmath/gimpvector.c
index c963ea7..97bf70d 100644
--- a/libgimpmath/gimpvector.c
+++ b/libgimpmath/gimpvector.c
@@ -33,6 +33,16 @@
 #include "gimpmath.h"
 
 
+/**
+ * SECTION: gimpvector
+ * @title: GimpVector
+ * @short_description: Utilities to set up and manipulate vectors.
+ * @see_also: #GimpMatrix2, #GimpMatrix3, #GimpMatrix4
+ *
+ * Utilities to set up and manipulate vectors.
+ **/
+
+
 /*************************/
 /* Some useful constants */
 /*************************/
diff --git a/libgimpmath/gimpvector.h b/libgimpmath/gimpvector.h
index 4ec383b..b3f56fe 100644
--- a/libgimpmath/gimpvector.h
+++ b/libgimpmath/gimpvector.h
@@ -29,16 +29,40 @@ G_BEGIN_DECLS
 
 /* For information look into the C source or the html documentation */
 
+/**
+ * GimpVector2:
+ * @x: the x axis
+ * @y: the y axis
+ *
+ * A two dimensional vector.
+ **/
 struct _GimpVector2
 {
   gdouble x, y;
 };
 
+/**
+ * GimpVector3:
+ * @x: the x axis
+ * @y: the y axis
+ * @z: the z axis
+ *
+ * A three dimensional vector.
+ **/
 struct _GimpVector3
 {
   gdouble x, y, z;
 };
 
+/**
+ * GimpVector4:
+ * @x: the x axis
+ * @y: the y axis
+ * @z: the z axis
+ * @w: the w axis
+ *
+ * A four dimensional vector.
+ **/
 struct _GimpVector4
 {
   gdouble x, y, z, w;