Some Doxygenization of the commentscxx-1-branch

8 files changed, 447 insertions, 269 deletions

diff --git a/src/mesa/tnl/NOTES b/src/mesa/tnl/NOTES
deleted file mode 100644
index c39b43485e..0000000000
--- a/src/mesa/tnl/NOTES
+++ /dev/null
@@ -1,102 +0,0 @@
-INTRODUCTION
-
-A generic, configurable software implementation of GL transformation &
-lighting.
-
-This module provides an implementation of the routines required by the
-'vtxfmt' mechanism of core mesa for tnl functionality in all
-combinations of compile and execute modes.
-
-Most current drivers use the tnl module exclusively to provide this
-functionality, though there is an experimental alternate
-implementation provided by the tnl_dd/t_dd_imm_* files which can
-handle a small subset of GL states in execute mode only.
-
-
-STATE
-
-To create and destroy the module:
-
-	GLboolean _tnl_CreateContext( GLcontext *ctx );
-	void _tnl_DestroyContext( GLcontext *ctx );
-
-The module is not active by default, and must be installed by calling
-_tnl_Wakeup().  This function installs internal tnl functions into all
-the vtxfmt dispatch hooks, thus taking over the task of transformation
-and lighting entirely:
-
-        void _tnl_wakeup_exec( GLcontext *ctx );
-	void _tnl_wakeup_save_exec( GLcontext *ctx );
-
-   
-This module tracks state changes internally and maintains derived
-values based on the current state.  For this to work, the driver
-ensure the following funciton is called whenever the state changes and
-the swsetup module is 'awake':
-
-	void _tnl_InvalidateState( GLcontext *ctx, GLuint new_state );
-
-There is no explicit call to put the tnl module to sleep.  Simply
-install other function pointers into all the vtxfmt dispatch slots,
-and (optionally) cease calling _tnl_InvalidateState().
-
-CUSTOMIZATION
-
-The module provides customizability through several mechanisms.  The
-most important is by allowing drivers to specify the pipeline through
-which vertex data is passed, including its eventual transfer to
-rasterization hardware (or software).
-
-The default pipeline is specified in t_pipeline.c, and is usually a
-starting point for driver pipelines.  Some drivers will remove a stage
-where hardware provides support for the implemented operation (for
-instance fog where per-pixel hardware fog is available, as in the dri
-tdfx driver), or add stages to shortcircuit latter operations (for
-example taking advantage of hardware support for strips and other
-higher-level primitives (for example the radeon driver).
-
-In addition, the following functions provide further tweaks:
-
-extern void
-_tnl_need_projected_coords( GLcontext *ctx, GLboolean flag );
-
-	- Direct the default vertex transformation stage to
-          produce/not produce projected clip coordinates.
-	  
-extern void
-_tnl_need_dlist_loopback( GLcontext *ctx, GLboolean flag );
-      
-        - Direct the display list component of the tnl module to
-          replay display lists as 'glVertex' type calls, rather than
-          passing the display list data directly into the tnl pipeline
-          mechanism.  
-
-	  This allows display lists to be replayed by the tnl module
-	  even when the module is not strictly active.
-
-
-extern void
-_tnl_need_dlist_norm_lengths( GLcontext *ctx, GLboolean flag );
-
-	- Direct the display list component to enable/disable caching
-          1/length values for display list normals.  Doing so is
-          ususally helpful when lighting is performed in software, but
-          wasteful otherwise.
-
-
-DRIVER INTERFACE
-
-The module itself offers a minimal driver interface:
-
-	 void (*RunPipeline)( GLcontext *ctx );
-
-Normally this is set to _tnl_RunPipeline(), however the driver can use
-this hook to wrap checks or other code around this call. 
-
-In addition, the driver interface for the default render pipeline
-stage is housed in the tnl context struct (this could be cleaner).  
-
-
-RENDER DRIVER INTERFACE
-
-See t_context.h for the definition and explanation of this.
\ No newline at end of file
diff --git a/src/mesa/tnl/t_array_api.c b/src/mesa/tnl/t_array_api.c
index 19cb19b716..edb2a8db92 100644
--- a/src/mesa/tnl/t_array_api.c
+++ b/src/mesa/tnl/t_array_api.c
@@ -1,4 +1,8 @@
-/* $Id: t_array_api.c,v 1.31 2003/03/01 01:50:26 brianp Exp $ */
+/**
+ * \file t_array_api.c
+ * \brief Vertex array API functions (glDrawArrays, etc)
+ * \author Keith Whitwell
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -24,11 +28,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/**
- * \file t_array_api.c
- * \brief Vertex array API functions (glDrawArrays, etc)
- * \author Keith Whitwell
- */
+/* $Id: t_array_api.c,v 1.31.2.1 2003/04/05 16:42:15 jrfonseca Exp $ */
 
 #include "glheader.h"
 #include "api_validate.h"
diff --git a/src/mesa/tnl/t_context.c b/src/mesa/tnl/t_context.c
index 6e8f48aaec..6693a27b0e 100644
--- a/src/mesa/tnl/t_context.c
+++ b/src/mesa/tnl/t_context.c
@@ -1,4 +1,8 @@
-/* $Id: t_context.c,v 1.31 2003/02/04 14:40:56 brianp Exp $ */
+/** 
+ * \file t_context.c
+ *
+ * \author Keith Whitwell <keith@tungstengraphics.com>
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -23,10 +27,129 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  *
- * Authors:
- *    Keith Whitwell <keith@tungstengraphics.com>
  */
 
+/* $Id: t_context.c,v 1.31.2.1 2003/04/05 16:42:15 jrfonseca Exp $ */
+ 
+/**
+ * \mainpage
+ * 
+ * \section TnlIntroduction Introduction
+ * 
+ * A generic, configurable software implementation of GL transformation &
+ * lighting.
+ * 
+ * This module provides an implementation of the routines required by the
+ * 'vtxfmt' mechanism of core mesa for tnl functionality in all
+ * combinations of compile and execute modes.
+ * 
+ * Most current drivers use the tnl module exclusively to provide this
+ * functionality, though there is an experimental alternate
+ * implementation provided by the tnl_dd/t_dd_imm_* files which can
+ * handle a small subset of GL states in execute mode only.
+ * 
+ *
+ * \section TnlState State
+ * 
+ * To create and destroy the module:
+ * 
+ * \code
+ * 	GLboolean _tnl_CreateContext( GLcontext *ctx );
+ * 	void _tnl_DestroyContext( GLcontext *ctx );
+ * \endcode
+ * 
+ * The module is not active by default, and must be installed by calling
+ * _tnl_Wakeup().  This function installs internal tnl functions into all
+ * the vtxfmt dispatch hooks, thus taking over the task of transformation
+ * and lighting entirely:
+ * 
+ * \code
+ * 	void _tnl_wakeup_exec( GLcontext *ctx );
+ * 	void _tnl_wakeup_save_exec( GLcontext *ctx );
+ * \endcode
+ *    
+ * This module tracks state changes internally and maintains derived
+ * values based on the current state.  For this to work, the driver
+ * ensure the following funciton is called whenever the state changes and
+ * the swsetup module is 'awake':
+ * 
+ * \code
+ * 	void _tnl_InvalidateState( GLcontext *ctx, GLuint new_state );
+ * \endcode
+ * 
+ * There is no explicit call to put the tnl module to sleep.  Simply
+ * install other function pointers into all the vtxfmt dispatch slots,
+ * and (optionally) cease calling _tnl_InvalidateState().
+ * 
+ * \section TnlCustomization Customization
+ * 
+ * The module provides customizability through several mechanisms.  The
+ * most important is by allowing drivers to specify the pipeline through
+ * which vertex data is passed, including its eventual transfer to
+ * rasterization hardware (or software).
+ * 
+ * The default pipeline is specified in t_pipeline.c, and is usually a
+ * starting point for driver pipelines.  Some drivers will remove a stage
+ * where hardware provides support for the implemented operation (for
+ * instance fog where per-pixel hardware fog is available, as in the dri
+ * tdfx driver), or add stages to shortcircuit latter operations (for
+ * example taking advantage of hardware support for strips and other
+ * higher-level primitives (for example the radeon driver).
+ * 
+ * In addition, the following functions provide further tweaks:
+ * 
+ * \code
+ * extern void
+ * _tnl_need_projected_coords( GLcontext *ctx, GLboolean flag );
+ * \endcode
+ * 
+ * 	- Direct the default vertex transformation stage to
+ *           produce/not produce projected clip coordinates.
+ * 	  
+ * \code
+ * extern void
+ * _tnl_need_dlist_loopback( GLcontext *ctx, GLboolean flag );
+ * \endcode
+ *       
+ *         - Direct the display list component of the tnl module to
+ *           replay display lists as 'glVertex' type calls, rather than
+ *           passing the display list data directly into the tnl pipeline
+ *           mechanism.  
+ * 
+ * 	  This allows display lists to be replayed by the tnl module
+ * 	  even when the module is not strictly active.
+ * 
+ * 
+ * \code
+ * extern void
+ * _tnl_need_dlist_norm_lengths( GLcontext *ctx, GLboolean flag );
+ * \endcode
+ * 
+ * 	- Direct the display list component to enable/disable caching
+ *           1/length values for display list normals.  Doing so is
+ *           ususally helpful when lighting is performed in software, but
+ *           wasteful otherwise.
+ * 
+ * 
+ * \section TnlDriverInterface Driver Interface
+ * 
+ * The module itself offers a minimal driver interface:
+ * 
+ * \code
+ * 	 void (*RunPipeline)( GLcontext *ctx );
+ * \endcode
+ * 
+ * Normally this is set to _tnl_RunPipeline(), however the driver can use
+ * this hook to wrap checks or other code around this call. 
+ * 
+ * In addition, the driver interface for the default render pipeline
+ * stage is housed in the tnl context struct (this could be cleaner).  
+ * 
+ * 
+ * \section TnlRenderDriverInterface Render Driver Interface
+ * 
+ * See t_context.h for the definition and explanation of this.
+ */
 
 #include "glheader.h"
 #include "imports.h"
diff --git a/src/mesa/tnl/t_context.h b/src/mesa/tnl/t_context.h
index b7153c545f..96a4d2be69 100644
--- a/src/mesa/tnl/t_context.h
+++ b/src/mesa/tnl/t_context.h
@@ -1,4 +1,8 @@
-/* $Id: t_context.h,v 1.46 2003/03/31 18:19:56 brianp Exp $ */
+/**
+ * \file t_context.h
+ * \brief TnL module datatypes and definitions.
+ * \author Keith Whitwell
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -24,11 +28,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/**
- * \file t_context.h
- * \brief TnL module datatypes and definitions.
- * \author Keith Whitwell
- */
+/* $Id: t_context.h,v 1.46.2.1 2003/04/05 16:42:15 jrfonseca Exp $ */
 
 #ifndef _T_CONTEXT_H
 #define _T_CONTEXT_H
@@ -44,38 +44,50 @@
 #define MAX_PIPELINE_STAGES     30
 
 
-/* Numbers for sizing immediate structs.
+/**
+ * \name Numbers for sizing immediate structs.
  */
+/*@{*/
 #define IMM_MAX_COPIED_VERTS  3
 #define IMM_MAXDATA          (216 + IMM_MAX_COPIED_VERTS)
 #define IMM_SIZE             (IMM_MAXDATA + MAX_CLIPPED_VERTICES)
+/*@}*/
 
 
-/* Values for IM->BeginState
+/**
+ * \name Values for immediate::BeginState
  */
-#define VERT_BEGIN_0    0x1	   /* glBegin (if initially inside beg/end) */
-#define VERT_BEGIN_1    0x2	   /* glBegin (if initially outside beg/end) */
-#define VERT_ERROR_0    0x4	   /* invalid_operation in initial state 0 */
-#define VERT_ERROR_1    0x8        /* invalid_operation in initial state 1 */
+/*@{*/
+#define VERT_BEGIN_0    0x1	   /**< glBegin (if initially inside beg/end) */
+#define VERT_BEGIN_1    0x2	   /**< glBegin (if initially outside beg/end) */
+#define VERT_ERROR_0    0x4	   /**< invalid_operation in initial state 0 */
+#define VERT_ERROR_1    0x8        /**< invalid_operation in initial state 1 */
+/*@}*/
 
 
-/* Flags to be added to the primitive enum in VB->Primitive.
+/**
+ * \name Flags to be added to the primitive enum in vertex_buffer::Primitive.
  */
-#define PRIM_MODE_MASK  0xff   /* Extract the actual primitive */
-#define PRIM_BEGIN      0x100  /* The prim starts here (not wrapped) */
-#define PRIM_END        0x200  /* The prim ends in this VB (does not wrap) */
-#define PRIM_PARITY     0x400  /* The prim wrapped on an odd number of verts */
-#define PRIM_LAST       0x800  /* No more prims in the VB */
+/*@{*/
+#define PRIM_MODE_MASK  0xff   /**< Extract the actual primitive */
+#define PRIM_BEGIN      0x100  /**< The prim starts here (not wrapped) */
+#define PRIM_END        0x200  /**< The prim ends in this VB (does not wrap) */
+#define PRIM_PARITY     0x400  /**< The prim wrapped on an odd number of verts */
+#define PRIM_LAST       0x800  /**< No more prims in the VB */
+/*@}*/
 
 
 /**
- * Flags that describe the inputs and outputs of pipeline stages, and
- * the contents of a vertex-cassette.  We reuse the VERT_BIT_* flags
- * defined in mtypes.h and add a bunch of new ones.
+ * \name Flags that describe the inputs and outputs of pipeline stages, and
+ * the contents of a vertex-cassette.  
+ *
+ * We reuse the VERT_BIT_* flags defined in mtypes.h and add a bunch of new
+ * ones.
  */
+/*@{*/
 /* bits 0..5 defined in mtypes.h */
-#define VERT_BIT_INDEX       VERT_BIT_SIX    /* a free vertex attrib bit */
-#define VERT_BIT_EDGEFLAG    VERT_BIT_SEVEN  /* a free vertex attrib bit */
+#define VERT_BIT_INDEX       VERT_BIT_SIX    /**< a free vertex attrib bit */
+#define VERT_BIT_EDGEFLAG    VERT_BIT_SEVEN  /**< a free vertex attrib bit */
 /* bits 8..15 defined in mtypes.h */
 #define VERT_BIT_EVAL_C1     (1 << 16)  /* imm only */
 #define VERT_BIT_EVAL_C2     (1 << 17)  /* imm only */
@@ -91,14 +103,20 @@
 #define VERT_BIT_POINT_SIZE  (1 << 27)  /* vb only, could reuse a bit */
 #define VERT_BIT_EYE         VERT_BIT_BEGIN /* vb only, reuse imm bit */
 #define VERT_BIT_CLIP        VERT_BIT_END   /* vb only, reuse imm bit*/
+/*@}*/
 
 
-/* Flags for IM->TexCoordSize.  Enough flags for 16 units.
+/**
+ * \name Flags for immediate::TexCoordSize.  
+ *
+ * Enough flags for 16 units.
  */
+/*@{*/
 #define TEX_0_SIZE_3          (unsigned)0x1
 #define TEX_0_SIZE_4          (unsigned)0x10001
 #define TEX_SIZE_3(unit)      (TEX_0_SIZE_3 << (unit))
 #define TEX_SIZE_4(unit)      (TEX_0_SIZE_4 << (unit))
+/*@}*/
 
 
 /* Shorthands.
@@ -144,22 +162,27 @@
 
 /**
  * Stores everything that can take place between a glBegin and glEnd.
- * Adjacent glBegin/glEnd pairs are stored back-to-back when there's no
+ *
+ * Adjacent glBegin()/glEnd() pairs are stored back-to-back when there's no
  * state changes between them.
+ *
  * Used for immediate mode rendering and display lists.
  */
 struct immediate
 {
    GLuint id, ref_count;
 
-   /* This must be saved when immediates are shared in display lists.
+   /**
+    * \name This must be saved when immediates are shared in display lists.
     */
+   /*@{*/
    GLuint CopyStart, Start, Count;
    GLuint LastData;		/* count or count+1 */
    GLuint AndFlag, OrFlag;
    GLuint TexSize;		/* keep track of texcoord sizes */
    GLuint BeginState, SavedBeginState;
    GLuint LastPrimitive;
+   /*@}*/
 
    GLuint ArrayEltFlags;	/* precalc'ed for glArrayElt */
    GLuint ArrayEltIncr;
@@ -174,10 +197,12 @@ struct immediate
    /* Temporary values created when vertices are copied into the
     * first 3 slots of the struct:
     */
+   /*@{*/
    GLuint CopyOrFlag;
    GLuint CopyAndFlag;
    GLuint CopyTexSize;
    GLuint Evaluated;
+   /*@}*/
 
 
    /* allocate storage for these on demand:
@@ -192,14 +217,16 @@ struct immediate
    GLuint  PrimitiveLength[IMM_SIZE]; /* BEGIN/END */
    GLuint  Flag[IMM_SIZE];	      /* VERT_BIT_* flags */
 
-   /* Attrib is an array [MAX_VERT_ATTRIBS] of pointer to array [][4]
+   /**
+    * Attrib is an array [MAX_VERT_ATTRIBS] of pointer to array [][4]
     * of GLfloat.
+    *
     * We only pre-allocate the vertex position array.  The other vertex
     * attribute arrays are only allocated when needed to save memory.
     */
    GLfloat (*Attrib[VERT_ATTRIB_MAX])[4];
 
-   GLfloat *NormalLengthPtr; /* length of normal vectors (display list only) */
+   GLfloat *NormalLengthPtr; /**< length of normal vectors (display list only) */
 
    GLuint  Elt[IMM_SIZE];
    GLubyte EdgeFlag[IMM_SIZE];
@@ -209,7 +236,9 @@ struct immediate
 
 struct vertex_arrays
 {
-   /* Conventional vertex attribute arrays */
+   /**
+    * \name Conventional vertex attribute arrays 
+    */
    GLvector4f  Obj;
    GLvector4f  Normal;
    struct gl_client_array Color;
@@ -220,7 +249,8 @@ struct vertex_arrays
    GLvector1ui Index;
    GLvector1ui Elt;
 
-   /* These attributes don't alias with the conventional attributes.
+   /**
+    * These attributes don't alias with the conventional attributes.
     * The GL_NV_vertex_program extension defines 16 extra sets of vertex
     * arrays which have precedent over the conventional arrays when enabled.
     */
@@ -233,47 +263,57 @@ struct vertex_arrays
  */
 typedef struct vertex_buffer
 {
-   /* Constant over life of the vertex_buffer.
+   /**
+    * \name Constant over life of the vertex_buffer.
     */
+   /*@{*/
    GLuint Size;
+   /*@}*/
 
-   /* Constant over the pipeline.
+   /**
+    * \name Constant over the pipeline.
     */
+   /*@{*/
    GLuint     Count;		              /* for everything except Elts */
    GLuint     FirstClipped;	              /* temp verts for clipping */
    GLuint     FirstPrimitive;	              /* usually zero */
+   /*@}*/
 
-   /* Pointers to current data.
-    */
-   GLuint      *Elts;		                /* VERT_BIT_ELT */
-   GLvector4f  *ObjPtr;		                /* VERT_BIT_POS */
-   GLvector4f  *EyePtr;		                /* VERT_BIT_EYE */
-   GLvector4f  *ClipPtr;	                /* VERT_BIT_CLIP */
-   GLvector4f  *NdcPtr;                         /* VERT_BIT_CLIP (2) */
-   GLubyte     ClipOrMask;	                /* VERT_BIT_CLIP (3) */
-   GLubyte     *ClipMask;		        /* VERT_BIT_CLIP (4) */
-   GLvector4f  *NormalPtr;	                /* VERT_BIT_NORMAL */
-   GLfloat     *NormalLengthPtr;	        /* VERT_BIT_NORMAL */
-   GLboolean   *EdgeFlag;	                /* VERT_BIT_EDGEFLAG */
-   GLvector4f  *TexCoordPtr[MAX_TEXTURE_COORD_UNITS]; /* VERT_TEX_0..n */
-   GLvector1ui *IndexPtr[2];	                /* VERT_BIT_INDEX */
-   struct gl_client_array *ColorPtr[2];	        /* VERT_BIT_COLOR0 */
-   struct gl_client_array *SecondaryColorPtr[2];/* VERT_BIT_COLOR1 */
-   GLvector4f  *PointSizePtr;	                /* VERT_BIT_POINT_SIZE */
-   GLvector4f  *FogCoordPtr;	                /* VERT_BIT_FOG */
-   struct gl_material (*Material)[2];         /* VERT_BIT_MATERIAL, optional */
-   GLuint      *MaterialMask;	              /* VERT_BIT_MATERIAL, optional */
-   GLuint      *Flag;		              /* VERT_BIT_* flags, optional */
-   GLuint      *Primitive;	              /* GL_(mode)|PRIM_* flags */
-   GLuint      *PrimitiveLength;	      /* integers */
-
-   /* Inputs to the vertex program stage */
+   /**
+    * \name Pointers to current data.
+    */
+   /*@{*/
+   GLuint      *Elts;		                /**< VERT_BIT_ELT */
+   GLvector4f  *ObjPtr;		                /**< VERT_BIT_POS */
+   GLvector4f  *EyePtr;		                /**< VERT_BIT_EYE */
+   GLvector4f  *ClipPtr;	                /**< VERT_BIT_CLIP */
+   GLvector4f  *NdcPtr;                         /**< VERT_BIT_CLIP (2) */
+   GLubyte     ClipOrMask;	                /**< VERT_BIT_CLIP (3) */
+   GLubyte     *ClipMask;		        /**< VERT_BIT_CLIP (4) */
+   GLvector4f  *NormalPtr;	                /**< VERT_BIT_NORMAL */
+   GLfloat     *NormalLengthPtr;	        /**< VERT_BIT_NORMAL */
+   GLboolean   *EdgeFlag;	                /**< VERT_BIT_EDGEFLAG */
+   GLvector4f  *TexCoordPtr[MAX_TEXTURE_COORD_UNITS]; /**< VERT_TEX_0..n */
+   GLvector1ui *IndexPtr[2];	                /**< VERT_BIT_INDEX */
+   struct gl_client_array *ColorPtr[2];	        /**< VERT_BIT_COLOR0 */
+   struct gl_client_array *SecondaryColorPtr[2];/**< VERT_BIT_COLOR1 */
+   GLvector4f  *PointSizePtr;	                /**< VERT_BIT_POINT_SIZE */
+   GLvector4f  *FogCoordPtr;	                /**< VERT_BIT_FOG */
+   struct gl_material (*Material)[2];           /**< VERT_BIT_MATERIAL, optional */
+   GLuint      *MaterialMask;	                /**< VERT_BIT_MATERIAL, optional */
+   GLuint      *Flag;		                /**< VERT_BIT_* flags, optional */
+   GLuint      *Primitive;	                /**< GL_(mode)|PRIM_* flags */
+   GLuint      *PrimitiveLength;	        /**< integers */
+   /*@}*/
+
+   /** Inputs to the vertex program stage */
    GLvector4f *AttribPtr[VERT_ATTRIB_MAX];      /* GL_NV_vertex_program */
 
    GLuint importable_data;
    void *import_source;
    void (*import_data)( GLcontext *ctx, GLuint flags, GLuint vecflags );
-   /* Callback to the provider of the untransformed input for the
+   /**<
+    * Callback to the provider of the untransformed input for the
     * render stage (or other stages) to call if they need to write into
     * write-protected arrays, or fixup the stride on input arrays.
     *
@@ -282,7 +322,8 @@ typedef struct vertex_buffer
     */
 
    GLuint LastClipped;
-   /* Private data from _tnl_render_stage that has no business being
+   /**<
+    * Private data from _tnl_render_stage that has no business being
     * in this struct.
     */
 
@@ -290,43 +331,56 @@ typedef struct vertex_buffer
 
 
 
-/* Describes an individual operation on the pipeline.
+/**
+ * Describes an individual operation on the pipeline.
  */
 struct gl_pipeline_stage {
    const char *name;
-   GLuint check_state;		/* All state referenced in check() --
+   GLuint check_state;		/**<
+				 * All state referenced in check() --
 				 * When is the pipeline_stage struct
 				 * itself invalidated?  Must be
 				 * constant.
 				 */
 
-   /* Usually constant or set by the 'check' callback:
+   /**
+    * \name Usually constant or set by the 'check' callback:
     */
-   GLuint run_state;		/* All state referenced in run() --
+   /*@{*/
+   GLuint run_state;		/**<
+				 * All state referenced in run() --
 				 * When is the cached output of the
 				 * stage invalidated?
 				 */
 
-   GLboolean active;		/* True if runnable in current state */
-   GLuint inputs;		/* VERT_* inputs to the stage */
-   GLuint outputs;		/* VERT_* outputs of the stage */
+   GLboolean active;		/**< True if runnable in current state */
+   GLuint inputs;		/**< VERT_* inputs to the stage */
+   GLuint outputs;		/**< VERT_* outputs of the stage */
+   /*@}*/
 
-   /* Set in _tnl_run_pipeline():
+   /**
+    * \name Set in _tnl_run_pipeline():
     */
-   GLuint changed_inputs;	/* Generated value -- inputs to the
+   /*@{*/
+   GLuint changed_inputs;	/**<
+				 * Generated value -- inputs to the
 				 * stage that have changed since last
 				 * call to 'run'.
 				 */
+   /*@}*/
 
-   /* Private data for the pipeline stage:
+   /**
+    * Private data for the pipeline stage:
     */
    void *privatePtr;
 
-   /* Free private data.  May not be null.
+   /**
+    * Free private data.  May not be null.
     */
    void (*destroy)( struct gl_pipeline_stage * );
 
-   /* Called from _tnl_validate_pipeline().  Must update all fields in
+   /**
+    * Called from _tnl_validate_pipeline().  Must update all fields in
     * the pipeline_stage struct for the current state.
     */
    void (*check)( GLcontext *ctx, struct gl_pipeline_stage * );
@@ -343,12 +397,15 @@ struct gl_pipeline_stage {
 };
 
 
+/**
+ * The pipeline.
+ */
 struct gl_pipeline {
-   GLuint build_state_trigger;	  /* state changes which require build */
-   GLuint build_state_changes;    /* state changes since last build */
-   GLuint run_state_changes;	  /* state changes since last run */
-   GLuint run_input_changes;	  /* VERT_* changes since last run */
-   GLuint inputs;		  /* VERT_* inputs to pipeline */
+   GLuint build_state_trigger;	  /**< state changes which require build */
+   GLuint build_state_changes;    /**< state changes since last build */
+   GLuint run_state_changes;	  /**< state changes since last run */
+   GLuint run_input_changes;	  /**< VERT_* changes since last run */
+   GLuint inputs;		  /**< VERT_* inputs to pipeline */
    struct gl_pipeline_stage stages[MAX_PIPELINE_STAGES+1];
    GLuint nr_stages;
 };
@@ -381,87 +438,116 @@ typedef void (*setup_func)( GLcontext *ctx,
 			    GLuint new_inputs);
 
 
+/**
+ * TNL device driver callbacks
+ */
 struct tnl_device_driver {
-   /***
-    *** TNL Pipeline
-    ***/
+   /**
+    * \name TNL Pipeline
+    */
+   /*@{*/
 
    void (*RunPipeline)(GLcontext *ctx);
-   /* Replaces PipelineStart/PipelineFinish -- intended to allow
+   /**<
+    * Replaces PipelineStart/PipelineFinish -- intended to allow
     * drivers to wrap _tnl_run_pipeline() with code to validate state
     * and grab/release hardware locks.  
     */
 
    void (*NotifyMaterialChange)(GLcontext *ctx);
-   /* Alert tnl-aware drivers of changes to material.
+   /**<
+    * Alert tnl-aware drivers of changes to material.
     */
 
    GLboolean (*NotifyBegin)(GLcontext *ctx, GLenum p);
-   /* Allow drivers to hook in optimized begin/end engines.
-    * Return value:  GL_TRUE - driver handled the begin
-    *                GL_FALSE - driver didn't handle the begin
+   /**<
+    * Allow drivers to hook in optimized begin/end engines.
+    *
+    * \return GL_TRUE if driver handled the begin, or GL_FALSE otherwise.
     */
+   /*@}*/
 
-   /***
-    *** Rendering -- These functions called only from t_vb_render.c
-    ***/
+   /**
+    * Rendering.
+    *
+    * These functions called only from t_vb_render.c
+    */
    struct {
-      void (*Start)(GLcontext *ctx);
-      void (*Finish)(GLcontext *ctx);
-      /* Called before and after all rendering operations, including DrawPixels,
+      /** 
+       * Called before and after all rendering operations, including DrawPixels,
        * ReadPixels, Bitmap, span functions, and CopyTexImage, etc commands.
        * These are a suitable place for grabbing/releasing hardware locks.
        */
+      /*@{*/
+      void (*Start)(GLcontext *ctx);
+      void (*Finish)(GLcontext *ctx);
+      /*@}*/
 
-      void (*PrimitiveNotify)(GLcontext *ctx, GLenum mode);
-      /* Called between RenderStart() and RenderFinish() to indicate the
+      /**
+       * Called between RenderStart() and RenderFinish() to indicate the
        * type of primitive we're about to draw.  Mode will be one of the
        * modes accepted by glBegin().
        */
+      void (*PrimitiveNotify)(GLcontext *ctx, GLenum mode);
 
-      interp_func Interp;
-      /* The interp function is called by the clipping routines when we need
+      /** 
+       * The interp function is called by the clipping routines when we need
        * to generate an interpolated vertex.  All pertinant vertex ancilliary
        * data should be computed by interpolating between the 'in' and 'out'
        * vertices.
        */
+      interp_func Interp;
 
-      copy_pv_func CopyPV;
-      /* The copy function is used to make a copy of a vertex.  All pertinant
+      /** 
+       * The copy function is used to make a copy of a vertex.  All pertinant
        * vertex attributes should be copied.
        */
+      copy_pv_func CopyPV;
 
-      void (*ClippedPolygon)( GLcontext *ctx, const GLuint *elts, GLuint n );
-      /* Render a polygon with <n> vertices whose indexes are in the <elts>
+      /** 
+       * Render a polygon with <n> vertices whose indexes are in the <elts>
        * array.
        */
+      void (*ClippedPolygon)( GLcontext *ctx, const GLuint *elts, GLuint n );
 
+      /** 
+       * Render a line between the two vertices given by indexes v0 and v1.
+       */
       void (*ClippedLine)( GLcontext *ctx, GLuint v0, GLuint v1 );
-      /* Render a line between the two vertices given by indexes v0 and v1. */
 
+      /** 
+       * \name Render points, lines, triangles, and quads.
+       * 
+       * These are only called via the T&L module.
+       */
+      /*@{*/
       points_func           Points; /* must now respect vb->elts */
       line_func             Line;
       triangle_func         Triangle;
       quad_func             Quad;
-      /* These functions are called in order to render points, lines,
-       * triangles and quads.  These are only called via the T&L module.
-       */
+      /*@}*/
 
+      /** 
+       * \name Render whole unclipped primitives (points, lines, linestrips,
+       * lineloops, etc).  
+       *
+       * The tables are indexed by the GL enum of the primitive to be rendered.
+       * RenderTabVerts is used for non-indexed arrays of vertices.
+       * RenderTabElts is used for indexed arrays of vertices.
+       */
+      /*@{*/
       render_func          *PrimTabVerts;
       render_func          *PrimTabElts;
-      /* Render whole unclipped primitives (points, lines, linestrips,
-       * lineloops, etc).  The tables are indexed by the GL enum of the
-       * primitive to be rendered.  RenderTabVerts is used for non-indexed
-       * arrays of vertices.  RenderTabElts is used for indexed arrays of
-       * vertices.
-       */
+      /*@}*/
 
-      void (*ResetLineStipple)( GLcontext *ctx );
-      /* Reset the hardware's line stipple counter.
+      /** 
+       * Reset the hardware's line stipple counter.
        */
+      void (*ResetLineStipple)( GLcontext *ctx );
 
       setup_func BuildVertices;
-      /* This function is called whenever new vertices are required for
+      /**< 
+       * This function is called whenever new vertices are required for
        * rendering.  The vertices in question are those n such that start
        * <= n < end.  The new_inputs parameter indicates those fields of
        * the vertex which need to be updated, if only a partial repair of
@@ -472,7 +558,8 @@ struct tnl_device_driver {
       
 
       GLboolean (*Multipass)( GLcontext *ctx, GLuint passno );
-      /* Driver may request additional render passes by returning GL_TRUE
+      /**< 
+       * Driver may request additional render passes by returning GL_TRUE
        * when this function is called.  This function will be called
        * after the first pass, and passes will be made until the function
        * returns GL_FALSE.  If no function is registered, only one pass
@@ -484,65 +571,82 @@ struct tnl_device_driver {
 };
    
 
+/**
+ * TNL context.
+ */
 typedef struct {
 
-   /* Driver interface.
+   /**
+    * Driver interface.
     */
    struct tnl_device_driver Driver;
 
-   /* Track whether the module is active.
+   /**
+    * Track whether the module is active.
     */
    GLboolean bound_exec;
 
-   /* Display list extensions
+   /**
+    * Display list extensions
     */
    GLuint opcode_vertex_cassette;
 
-   /* Pipeline
+   /**
+    * Pipeline
     */
    struct gl_pipeline pipeline;
    struct vertex_buffer vb;
 
-   /* GLvectors for binding to vb:
+   /**
+    * \name GLvectors for binding to vb:
     */
+   /*@{*/
    struct vertex_arrays imm_inputs;
    struct vertex_arrays array_inputs;
    GLuint *tmp_primitive;
    GLuint *tmp_primitive_length;
+   /*@}*/
 
-   /* Set when executing an internally generated begin/end object.  If
+   /**
+    * Set when executing an internally generated begin/end object.  If
     * such an object is encountered in a display list, it will be
     * replayed only if the list is outside any existing begin/end
     * objects.  
     */
    GLboolean ReplayHardBeginEnd;
 
-   /* Note which vertices need copying over succesive immediates.
+   /**
+    * \name Note which vertices need copying over succesive immediates.
+    * 
     * Will add save versions to precompute vertex copying where
     * possible.
     */
+   /*@{*/
    struct immediate *ExecCopySource;
    GLuint ExecCopyCount;
    GLuint ExecCopyElts[IMM_MAX_COPIED_VERTS];
    GLuint ExecCopyTexSize;
    GLuint ExecParity;
+   /*@}*/
 
    GLuint DlistPrimitive;
    GLuint DlistPrimitiveLength;
    GLuint DlistLastPrimitive;
 
-   /* Cache a single free immediate (refcount == 0)
+   /**
+    * Cache a single free immediate (refcount == 0)
     */
    struct immediate *freed_immediate;   
 
-   /* Probably need a better configuration mechanism:
+   /**
+    * Probably need a better configuration mechanism:
     */
    GLboolean NeedNdcCoords;
    GLboolean LoopbackDListCassettes;
    GLboolean CalcDListNormalLengths;
    GLboolean IsolateMaterials;
 
-   /* Derived state and storage for _tnl_eval_vb:
+   /** Derived state and storage for _tnl_eval_vb:
     */
    struct tnl_eval_store eval;
 
@@ -554,8 +658,9 @@ typedef struct {
 } TNLcontext;
 
 
-
+/** Get the TNL context pointer from the GL context pointer */
 #define TNL_CONTEXT(ctx) ((TNLcontext *)(ctx->swtnl_context))
+/** Get the current immediate pointer from the GL context pointer */
 #define TNL_CURRENT_IM(ctx) ((struct immediate *)(ctx->swtnl_im))
 
 
@@ -567,9 +672,10 @@ extern void _tnl_MakeCurrent( GLcontext *ctx,
 			      GLframebuffer *readBuffer );
 
 
-/*
- * Macros for fetching current input buffer.
+/**
+ * \name Macros for fetching current input buffer.
  */
+/*@{*/
 #ifdef THREADS
 #define GET_IMMEDIATE  struct immediate *IM = TNL_CURRENT_IM(((GLcontext *) (_glapi_Context ? _glapi_Context : _glapi_get_context())))
 #define SET_IMMEDIATE(ctx, im)  ctx->swtnl_im = (void *)im
@@ -582,6 +688,7 @@ do {						\
    _tnl_CurrentInput = im;			\
 } while (0)
 #endif
+/*@}*/
 
 
 #endif
diff --git a/src/mesa/tnl/t_imm_api.c b/src/mesa/tnl/t_imm_api.c
index 0eef3b735c..81093c16b7 100644
--- a/src/mesa/tnl/t_imm_api.c
+++ b/src/mesa/tnl/t_imm_api.c
@@ -1,4 +1,7 @@
-/* $Id: t_imm_api.c,v 1.40 2003/03/31 18:19:56 brianp Exp $ */
+/**
+ * \file t_imm_api.c
+ * \brief TNL immediate API.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -27,6 +30,7 @@
  *    Keith Whitwell <keith@tungstengraphics.com>
  */
 
+/* $Id: t_imm_api.c,v 1.40.2.1 2003/04/05 16:42:15 jrfonseca Exp $ */
 
 
 #include "glheader.h"
@@ -47,7 +51,9 @@
 #include "t_imm_dlist.h"
 
 
-/* A cassette is full or flushed on a statechange.
+/**
+ * 
+ * A cassette is full or flushed on a statechange.
  */
 void _tnl_flush_immediate( GLcontext *ctx, struct immediate *IM )
 {
@@ -79,7 +85,8 @@ void _tnl_flush_immediate( GLcontext *ctx, struct immediate *IM )
 }
 
 
-/* Hook for ctx->Driver.FlushVertices:
+/**
+ * Hook for dd_function_table::FlushVertices
  */
 void _tnl_flush_vertices( GLcontext *ctx, GLuint flags )
 {
@@ -400,7 +407,8 @@ _tnl_End(void)
 }
 
 
-/* If the given vertex attribute array hasn't been allocated yet,
+/**
+ * If the given vertex attribute array hasn't been allocated yet,
  * allocate it now.
  */
 #define CHECK_ATTRIB_ARRAY(IM, ATTR)					\
@@ -414,6 +422,9 @@ _tnl_End(void)
    }
 
 
+/**
+ * Update the color attribute in the immediate structure.
+ */
 #define COLOR( r, g, b, a )					\
 {								\
    GET_IMMEDIATE;						\
@@ -489,7 +500,9 @@ _tnl_Color4ubv( const GLubyte *v)
 }
 
 
-
+/**
+ * Update the secondary color attribute in the immediate structure.
+ */
 #define SECONDARY_COLOR( r, g, b )			\
 {							\
    GET_IMMEDIATE;					\
@@ -597,6 +610,9 @@ _tnl_Indexiv( const GLint *c )
 }
 
 
+/**
+ * Update the normal attribute in the immediate structure.
+ */
 #define NORMAL( x, y, z )				\
 {							\
    GET_IMMEDIATE;					\
@@ -639,6 +655,10 @@ _tnl_Normal3fv( const GLfloat *v )
 }
 
 
+/**
+ * \name Texture coordinates
+ */
+/*@{*/
 
 #define TEXCOORD1(s)				\
 {						\
@@ -754,8 +774,14 @@ _tnl_TexCoord4fv( const GLfloat *v )
    TEXCOORD4(v[0], v[1], v[2], v[3]);
 }
 
+/*@}*/
 
 
+/**
+ * \name Vertex coordinates
+ */
+/*@{*/
+
 /* KW: Run into bad problems in vertex copying if we don't fully pad
  *     the incoming vertices.
  */
@@ -887,16 +913,18 @@ _tnl_Vertex4fv( const GLfloat *v )
    VERTEX4F( IM, v[0], v[1], v[2], v[3] );
 }
 
+/*@}*/
 
 
 
-/*
+/**
  * GL_ARB_multitexture
  *
  * Note: the multitexture spec says that specifying an invalid target
  * has undefined results and does not have to generate an error.  Just
  * don't crash.  We no-op on invalid targets.
  */
+/*@{*/
 
 #define MAX_TARGET (GL_TEXTURE0_ARB + MAX_TEXTURE_COORD_UNITS)
 
@@ -1027,6 +1055,7 @@ _tnl_MultiTexCoord4fvARB(GLenum target, const GLfloat *v)
    MULTI_TEXCOORD4( target, v[0], v[1], v[2], v[3] );
 }
 
+/*@}*/
 
 
 /* KW: Because the eval values don't become 'current', fixup will flow
@@ -1229,10 +1258,12 @@ _tnl_VertexAttrib4fvNV( GLuint index, const GLfloat *v )
 }   
 
 
-/* Execute a glRectf() function.  _tnl_hard_begin() ensures the check
- * on outside_begin_end is executed even in compiled lists.  These
- * vertices can now participate in the same immediate as regular ones,
- * even in most display lists.  
+/**
+ * Execute a glRectf() function.  
+ *
+ * _tnl_hard_begin() ensures the check on outside_begin_end is executed even in
+ * compiled lists.  These vertices can now participate in the same immediate as
+ * regular ones, even in most display lists.  
  */
 static void
 _tnl_Rectf( GLfloat x1, GLfloat y1, GLfloat x2, GLfloat y2 )
@@ -1345,6 +1376,9 @@ _tnl_Materialfv( GLenum face, GLenum pname, const GLfloat *params )
    }
 }
 
+/**
+ * Initialize our part of the GLvertexformat structure.
+ */
 void _tnl_imm_vtxfmt_init( GLcontext *ctx )
 {
    GLvertexformat *vfmt = &(TNL_CONTEXT(ctx)->vtxfmt);
diff --git a/src/mesa/tnl/t_imm_api.h b/src/mesa/tnl/t_imm_api.h
index 6615a9ce93..5d9dcaa905 100644
--- a/src/mesa/tnl/t_imm_api.h
+++ b/src/mesa/tnl/t_imm_api.h
@@ -1,5 +1,3 @@
-/* $Id: t_imm_api.h,v 1.5 2002/04/09 16:56:52 keithw Exp $ */
-
 /*
  * Mesa 3-D graphics library
  * Version:  4.1
@@ -24,6 +22,8 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+/* $Id: t_imm_api.h,v 1.5.8.1 2003/04/05 16:42:15 jrfonseca Exp $ */
+
 
 #ifndef _T_VTXFMT_H
 #define _T_VTXFMT_H
@@ -40,17 +40,19 @@ extern void _tnl_Begin( GLenum mode );
 extern void _tnl_End(void);
 
 
-/* TNL-private internal functions for building higher-level operations:
+/**
+ * \name TNL-private internal functions for building higher-level operations
  */
+/*@{*/
 extern GLboolean _tnl_hard_begin( GLcontext *ctx, GLenum p );
 extern void _tnl_end( GLcontext *ctx );
 extern void _tnl_vertex2f( GLcontext *ctx, GLfloat x, GLfloat y );
 extern void _tnl_eval_coord1f( GLcontext *CC, GLfloat u );
 extern void _tnl_eval_coord2f( GLcontext *CC, GLfloat u, GLfloat v );
 extern void _tnl_array_element( GLcontext *CC, GLint i );
+/*@}*/
+
 
-/* Initialize our part of the vtxfmt struct:
- */
 extern void _tnl_imm_vtxfmt_init( GLcontext *ctx );
 
 
diff --git a/src/mesa/tnl/t_imm_exec.c b/src/mesa/tnl/t_imm_exec.c
index 97f49762ad..1d0ec0a9bd 100644
--- a/src/mesa/tnl/t_imm_exec.c
+++ b/src/mesa/tnl/t_imm_exec.c
@@ -1,4 +1,8 @@
-/* $Id: t_imm_exec.c,v 1.44 2003/03/01 01:50:27 brianp Exp $ */
+/**
+ * \file tnl/t_imm_exec.c
+ * \brief Setup to execute immediate-mode vertex data.
+ * \author Keith Whitwell
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -24,11 +28,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/**
- * \file tnl/t_imm_exec.c
- * \brief Setup to execute immediate-mode vertex data.
- * \author Keith Whitwell
- */
+/* $Id: t_imm_exec.c,v 1.44.2.1 2003/04/05 16:42:15 jrfonseca Exp $ */
 
 #include "glheader.h"
 #include "colormac.h"
diff --git a/src/mesa/tnl/tnl.h b/src/mesa/tnl/tnl.h
index 1fe7b451cc..d651aa51cb 100644
--- a/src/mesa/tnl/tnl.h
+++ b/src/mesa/tnl/tnl.h
@@ -1,4 +1,12 @@
-/* $Id: tnl.h,v 1.10 2002/10/29 20:29:04 brianp Exp $ */
+/**
+ * \file tnl.h
+ * \author Keith Whitwell <keith@tungstengraphics.com>
+ * \file TnL public interface.
+ * 
+ * These are the public-access functions exported from tnl.  (A few
+ * more are currently hooked into dispatch directly by the module
+ * itself.)
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -22,11 +30,10 @@
  * BRIAN PAUL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- *
- * Authors:
- *    Keith Whitwell <keith@tungstengraphics.com>
  */
 
+/* $Id: tnl.h,v 1.10.6.1 2003/04/05 16:42:15 jrfonseca Exp $ */
+
 #ifndef _TNL_H
 #define _TNL_H
 
@@ -34,10 +41,6 @@
 
 
 
-/* These are the public-access functions exported from tnl.  (A few
- * more are currently hooked into dispatch directly by the module
- * itself.)
- */
 extern GLboolean
 _tnl_CreateContext( GLcontext *ctx );
 
@@ -47,22 +50,31 @@ _tnl_DestroyContext( GLcontext *ctx );
 extern void
 _tnl_InvalidateState( GLcontext *ctx, GLuint new_state );
 
-/* Functions to revive the tnl module after being unhooked from
+
+/**
+ * \name Functions to revive the tnl module after being unhooked from
  * dispatch and/or driver callbacks.
  */
+/*@{*/
 
-/* Restore just the ctx->Exec table:
+/**
+ * Restore just the ctx->Exec table
  */
 extern void
 _tnl_wakeup_exec( GLcontext *ctx );
 
-/* Restore both ctx->Exec and ctx->Save:
+/**
+ * Restore both ctx->Exec and ctx->Save: 
  */
 extern void
 _tnl_wakeup_save_exec( GLcontext *ctx );
+/*@}*/
 
-/* Driver configuration options:
+
+/**
+ * Driver configuration options
  */
+/*@{*/
 extern void
 _tnl_need_projected_coords( GLcontext *ctx, GLboolean flag );
 
@@ -74,5 +86,7 @@ _tnl_need_dlist_norm_lengths( GLcontext *ctx, GLboolean flag );
 
 extern void
 _tnl_isolate_materials( GLcontext *ctx, GLboolean flag );
+/*@}*/
+
 
 #endif