Final documentation fixes and enhancements.

30 files changed, 438 insertions, 238 deletions

diff --git a/src/mesa/glapi/glthread.h b/src/mesa/glapi/glthread.h
index e2eecd11201..d63d0650f53 100644
--- a/src/mesa/glapi/glthread.h
+++ b/src/mesa/glapi/glthread.h
@@ -3,7 +3,7 @@
  * \brief Thread support for GL dispatch.
  * 
  * \if subset
- * \brief (No-op.)
+ * \brief (No-op)
  *
  * \endif
  *
@@ -42,7 +42,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: glthread.h,v 1.11.6.3 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: glthread.h,v 1.11.6.4 2003/03/23 23:22:48 jrfonseca Exp $ */
 
 
 #ifndef GLTHREAD_H
@@ -254,28 +254,28 @@ typedef GLuint _glthread_Mutex;
 /** 
  * \brief Declare a non-local mutex.
  *
- * No-op.
+ * No-op
  */
 #define _glthread_DECLARE_STATIC_MUTEX(name)  static _glthread_Mutex name = 0
 
 /** 
  * \brief Initialize a mutex.
  *
- * No-op.
+ * No-op
  */
 #define _glthread_INIT_MUTEX(name)  (void) name
 
 /** 
  * \brief Lock a mutex.
  *
- * No-op.
+ * No-op
  */
 #define _glthread_LOCK_MUTEX(name)  (void) name
 
 /** 
  * \brief Unlock a mutex.
  *
- * No-op.
+ * No-op
  */
 #define _glthread_UNLOCK_MUTEX(name)  (void) name
 
diff --git a/src/mesa/main/accum.h b/src/mesa/main/accum.h
index accad683c20..b18aa2df802 100644
--- a/src/mesa/main/accum.h
+++ b/src/mesa/main/accum.h
@@ -3,7 +3,7 @@
  * \brief Accumulation buffer operations.
  * 
  * \if subset
- * \brief (No-op.)
+ * \brief (No-op)
  *
  * \endif
  */
@@ -32,7 +32,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: accum.h,v 1.6.8.2 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: accum.h,v 1.6.8.3 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 
 #ifndef ACCUM_H
diff --git a/src/mesa/main/attrib.h b/src/mesa/main/attrib.h
index 146e3f2a9c6..d3eadf02ee6 100644
--- a/src/mesa/main/attrib.h
+++ b/src/mesa/main/attrib.h
@@ -3,7 +3,7 @@
  * \brief Attribute stacks.
  * 
  * \if subset
- * \brief (No-op.)
+ * \brief (No-op)
  *
  * \endif
  */
@@ -32,7 +32,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: attrib.h,v 1.6.6.2 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: attrib.h,v 1.6.6.3 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 
 #ifndef ATTRIB_H
diff --git a/src/mesa/main/blend.c b/src/mesa/main/blend.c
index 271d879893e..8e577e6dfda 100644
--- a/src/mesa/main/blend.c
+++ b/src/mesa/main/blend.c
@@ -27,7 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: blend.c,v 1.38.4.4 2003/03/22 16:49:58 jrfonseca Exp $ */
+/* $Id: blend.c,v 1.38.4.5 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 
 #include "glheader.h"
@@ -40,16 +40,16 @@
 
 
 /**
- * \brief Specify blending operation.
+ * \brief Specify the blending operation.
  *
  * \param sfactor source factor operator.
  * \param dfactor destination factor operator.
  *
  * \sa glBlendFunc().
  * 
- * Verifies the parameters and updates gl_colorbuffer_attrib.
- * On a change, flush the vertices and notify the driver via
- * dd_function_table::BlendFunc.
+ * Verifies the parameters and updates gl_colorbuffer_attrib.  On a change,
+ * flushes the vertices and notifies the driver via
+ * dd_function_table::BlendFunc callback.
  */
 void
 _mesa_BlendFunc( GLenum sfactor, GLenum dfactor )
@@ -346,18 +346,18 @@ _mesa_BlendEquation( GLenum mode )
 
 
 /**
- * \brief Set the blend color.
+ * \brief Set the blending color.
  *
- * \param red red component.
- * \param green green component.
- * \param blue blue component.
- * \param alpha alpha component.
+ * \param red red color component.
+ * \param green green color component.
+ * \param blue blue color component.
+ * \param alpha alpha color component.
  *
  * \sa glBlendColor().
  *
- * Clamps the parameters and updates gl_colorbuffer_attrib::BlendColor.
- * On a change, flush the vertices and notify the driver via
- * dd_function_table::BlendColor.
+ * Clamps the parameters and updates gl_colorbuffer_attrib::BlendColor.  On a
+ * change, flushes the vertices and notifies the driver via
+ * dd_function_table::BlendColor callback.
  */
 void
 _mesa_BlendColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha )
@@ -383,14 +383,14 @@ _mesa_BlendColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha )
 
 
 /**
- * \brief Specify alpha test function.
+ * \brief Specify the alpha test function.
  *
  * \param func alpha comparision function.
  * \param ref reference value.
  *
  * Verifies the parameters and updates gl_colorbuffer_attrib. 
- * On a change, flush the vertices and notify the driver via
- * dd_function_table::AlphaFunc.
+ * On a change, flushes the vertices and notifies the driver via
+ * dd_function_table::AlphaFunc callback.
  */
 void
 _mesa_AlphaFunc( GLenum func, GLclampf ref )
@@ -432,10 +432,10 @@ _mesa_AlphaFunc( GLenum func, GLclampf ref )
  *
  * \param opcode operation.
  *
- * Verifies \p opcode is a valid enum and updates
+ * Verifies that \p opcode is a valid enum and updates
 gl_colorbuffer_attrib::LogicOp.
- * Flushes the vertices and notifies the driver via
- * dd_function_table::LogicOp if it has changed.
+ * On a change, flushes the vertices and notifies the driver via the
+ * dd_function_table::LogicOpcode callback.
  */
 void
 _mesa_LogicOp( GLenum opcode )
@@ -498,16 +498,16 @@ _mesa_IndexMask( GLuint mask )
 /**
  * \brief Enable or disable writing of frame buffer color components.
  *
- * \param red red color component.
- * \param green green color component.
- * \param blue blue color component.
- * \param alpha alpha component.
+ * \param red whether to mask writing of the red color component.
+ * \param green whether to mask writing of the green color component.
+ * \param blue whether to mask writing of the blue color component.
+ * \param alpha whether to mask writing of the alpha color component.
  *
  * \sa glColorMask().
  *
- * Sets the appropriate value of gl_colorbuffer_attrib::ColorMask.  Flushes
- * the vertices and notifies the driver via dd_function_table::ColorMask if
- * it has changed.
+ * Sets the appropriate value of gl_colorbuffer_attrib::ColorMask.  On a
+ * change, flushes the vertices and notifies the driver via the
+ * dd_function_table::ColorMask callback.
  */
 void
 _mesa_ColorMask( GLboolean red, GLboolean green,
@@ -539,9 +539,17 @@ _mesa_ColorMask( GLboolean red, GLboolean green,
 }
 
 /**********************************************************************/
-/*****                      Initialization                        *****/
-/**********************************************************************/
+/** \name Initialization */
+/*@{*/
 
+/**
+ * \brief Initialization of the context color data.
+ *
+ * \param ctx GL context.
+ *
+ * Initializes the related fields in the context color attribute group,
+ * __GLcontextRec::Color.
+ */
 void _mesa_init_color( GLcontext * ctx )
 {
    /* Color buffer group */
@@ -577,3 +585,5 @@ void _mesa_init_color( GLcontext * ctx )
       ctx->Color._DrawDestMask = FRONT_LEFT_BIT;
    }
 }
+
+/*@}*/
diff --git a/src/mesa/main/buffers.c b/src/mesa/main/buffers.c
index e6ed06690d1..4777ec3ac61 100644
--- a/src/mesa/main/buffers.c
+++ b/src/mesa/main/buffers.c
@@ -27,7 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: buffers.c,v 1.42.4.3 2003/03/20 09:19:59 keithw Exp $ */
+/* $Id: buffers.c,v 1.42.4.4 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 
 #include "glheader.h"
@@ -74,9 +74,9 @@ _mesa_ClearIndex( GLfloat c )
  *
  * \sa glClearColor().
  *
- * Clamps the parameters and updates gl_colorbuffer_attrib::ClearColor.  On
- * a change, flush the vertices and notify the driver via
- * dd_function_table::ClearColor.
+ * Clamps the parameters and updates gl_colorbuffer_attrib::ClearColor.  On a
+ * change, flushes the vertices and notifies the driver via the
+ * dd_function_table::ClearColor callback.
  */
 void
 _mesa_ClearColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha )
@@ -108,10 +108,10 @@ _mesa_ClearColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha )
  * 
  * \param mask bit-mask indicating the buffers to be cleared.
  *
- * Verifies the parameter. If __GLcontextRec::NewState is set calls
- * _mesa_update_state() to update gl_frame_buffer::_Xmin, etc. If the
- * rasterization mode is set to GL_RENDER requests the driver to clean the
- * buffers, via dd_function_table::Clear.
+ * Flushes the vertices and verifies the parameter. If __GLcontextRec::NewState
+ * is set then calls _mesa_update_state() to update gl_frame_buffer::_Xmin,
+ * etc. If the rasterization mode is set to GL_RENDER then requests the driver
+ * to clear the buffers, via the dd_function_table::Clear callback.
  */ 
 void
 _mesa_Clear( GLbitfield mask )
@@ -168,10 +168,10 @@ _mesa_Clear( GLbitfield mask )
  *
  * \sa glDrawBuffer().
  *
- * Verifies the parameter and updates the
+ * Flushes the vertices and verifies the parameter and updates the
  * gl_colorbuffer_attrib::_DrawDestMask bitfield. Marks new color state in
- * __GLcontextRec::NewState and notifies the driver via
- * dd_function_table::DrawBuffer.
+ * __GLcontextRec::NewState and notifies the driver via the
+ * dd_function_table::DrawBuffer callback.
  */
 void
 _mesa_DrawBuffer( GLenum mode )
@@ -509,8 +509,8 @@ _mesa_SampleCoverageARB(GLclampf value, GLboolean invert)
  * \sa glScissor().
  *
  * Verifies the parameters and updates __GLcontextRec::Scissor. On a
- * change flush the vertices and notifies the driver via
- * dd_function_table::Scissor.
+ * change flushes the vertices and notifies the driver via
+ * the dd_function_table::Scissor callback.
  */
 void
 _mesa_Scissor( GLint x, GLint y, GLsizei width, GLsizei height )
@@ -543,10 +543,15 @@ _mesa_Scissor( GLint x, GLint y, GLsizei width, GLsizei height )
 }
 
 /**********************************************************************/
-/*****                    State management                        *****/
-/**********************************************************************/
+/** \name State management */
+/*@{*/
 
-/* Update screen bounds.
+/**
+ * \brief Update screen bounds.
+ *
+ * \param ctx GL context.
+ *
+ * Update gl_frame_buffer::_Xmin, and etc.
  */
 void _mesa_update_buffers( GLcontext *ctx )
 {
@@ -570,11 +575,21 @@ void _mesa_update_buffers( GLcontext *ctx )
    }
 }
 
+/*@}*/
+
 			   
 /**********************************************************************/
-/*****                      Initialization                        *****/
-/**********************************************************************/
+/** \name Initialization */
+/*@{*/
 
+/**
+ * \brief Initialize the context scissor data.
+ *
+ * \param ctx GL context.
+ * 
+ * Initializes the __GLcontextRec::Scissor and __GLcontextRec::Multisample
+ * attribute groups, and related constants in __GLcontextRec::Const.
+ */
 void _mesa_init_buffers( GLcontext * ctx )
 {
    /* Scissor group */
@@ -597,4 +612,4 @@ void _mesa_init_buffers( GLcontext * ctx )
 
 }
 
-
+/*@}*/
diff --git a/src/mesa/main/colormac.h b/src/mesa/main/colormac.h
index fafb58a9e4f..cb5f31c7c93 100644
--- a/src/mesa/main/colormac.h
+++ b/src/mesa/main/colormac.h
@@ -27,7 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: colormac.h,v 1.11.6.1 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: colormac.h,v 1.11.6.2 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 
 #ifndef COLORMAC_H
@@ -144,7 +144,7 @@
 
 
 /**
- * Convert 3 channels at once.
+ * \brief Convert 3 channels at once.
  *
  * \param dst pointer to destination GLchan[3] array.
  * \param f pointer to source GLfloat[3] array.
diff --git a/src/mesa/main/colortab.h b/src/mesa/main/colortab.h
index 867c7bc7a7e..d04cba207aa 100644
--- a/src/mesa/main/colortab.h
+++ b/src/mesa/main/colortab.h
@@ -3,7 +3,7 @@
  * \brief Color tables.
  * 
  * \if subset
- * \brief (No-op.)
+ * \brief (No-op)
  *
  * \endif
  */
@@ -32,7 +32,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: colortab.h,v 1.9.8.4 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: colortab.h,v 1.9.8.5 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 
 #ifndef COLORTAB_H
diff --git a/src/mesa/main/context.c b/src/mesa/main/context.c
index e1896ac6255..114fe92ea2f 100644
--- a/src/mesa/main/context.c
+++ b/src/mesa/main/context.c
@@ -28,7 +28,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: context.c,v 1.188.2.1.2.15 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: context.c,v 1.188.2.1.2.16 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 /**
  * \mainpage Mesa Core Module
@@ -145,8 +145,12 @@ free_shared_state( GLcontext *ctx, struct gl_shared_state *ss );
 
 
 /**********************************************************************/
-/** \name OpenGL SI-style interface (new in Mesa 3.5)                 */
-/**********************************************************************/
+/** \name OpenGL SI-style interface (new in Mesa 3.5)
+ *
+ * \if subset
+ * \note Most of these functions are never called in the Mesa subset.
+ * \endif
+ */
 /*@{*/
 
 /**
@@ -155,8 +159,10 @@ free_shared_state( GLcontext *ctx, struct gl_shared_state *ss );
  * \param gc context.
  * \return GL_TRUE on success, or GL_FALSE on failure.
  * 
+ * \ifnot subset
  * Called by window system/device driver (via __GLexports::destroyCurrent) when
  * the rendering context is to be destroyed.
+ * \endif
  *
  * Frees the context data and the context structure.
  */
@@ -176,10 +182,12 @@ _mesa_destroyContext(__GLcontext *gc)
  * \param gc context.
  * \return GL_TRUE on success, or GL_FALSE on failure.
  *
+ * \ifnot subset
  * Called by window system/device driver (via __GLexports::loseCurrent)
  * when the rendering context is made non-current.
+ * \endif
  *
- * No-op.
+ * No-op
  */
 GLboolean
 _mesa_loseCurrent(__GLcontext *gc)
@@ -194,10 +202,12 @@ _mesa_loseCurrent(__GLcontext *gc)
  * \param gc context.
  * \return GL_TRUE on success, or GL_FALSE on failure.
  *
+ * \ifnot subset
  * Called by window system/device driver (via __GLexports::makeCurrent)
  * when the rendering context is made current.
+ * \endif
  *
- * No-op.
+ * No-op
  */
 GLboolean
 _mesa_makeCurrent(__GLcontext *gc)
@@ -212,7 +222,11 @@ _mesa_makeCurrent(__GLcontext *gc)
  * \param gc context.
  * \return GL_TRUE on success, or GL_FALSE on failure.
  *
+ * \ifnot subset
  * Called by window system/device driver (via __GLexports::shareContext)
+ * \endif
+ *
+ * Update the shared context reference count, gl_shared_state::RefCount.
  */
 GLboolean
 _mesa_shareContext(__GLcontext *gc, __GLcontext *gcShare)
@@ -249,7 +263,7 @@ _mesa_copyContext(__GLcontext *dst, const __GLcontext *src, GLuint mask)
 }
 #endif
 
-/** No-op. */
+/** \brief No-op */
 GLboolean
 _mesa_forceCurrent(__GLcontext *gc)
 {
@@ -282,7 +296,7 @@ _mesa_notifyResize(__GLcontext *gc)
  * 
  * Called when the context's window/buffer is going to be destroyed. 
  *
- * No-op.
+ * No-op
  */
 void
 _mesa_notifyDestroy(__GLcontext *gc)
@@ -304,26 +318,27 @@ _mesa_notifySwapBuffers(__GLcontext *gc)
    FLUSH_VERTICES( gc, 0 );
 }
 
-/** \brief No-op. */
+/** \brief No-op */
 struct __GLdispatchStateRec *
 _mesa_dispatchExec(__GLcontext *gc)
 {
    return NULL;
 }
 
-/** \brief No-op. */
+/** \brief No-op */
 void
 _mesa_beginDispatchOverride(__GLcontext *gc)
 {
 }
 
-/** \brief No-op. */
+/** \brief No-op */
 void
 _mesa_endDispatchOverride(__GLcontext *gc)
 {
 }
 
 /**
+ * \ifnot subset
  * \brief Setup the exports.  
  *
  * The window system will call these functions when it needs Mesa to do
@@ -334,6 +349,12 @@ _mesa_endDispatchOverride(__GLcontext *gc)
  * structure.  The XMesa-style functions should then call the _mesa_*
  * version of these functions.  This is an approximation to OO design
  * (inheritance and virtual functions).
+ * \endif
+ *
+ * \if subset
+ * \brief No-op.
+ * 
+ * \endif
  */
 static void
 _mesa_init_default_exports(__GLexports *exports)
@@ -561,8 +582,8 @@ _mesa_destroy_visual( GLvisual *vis )
 /**
  * \brief Create a new framebuffer.  
  *
- * A GLframebuffer is a struct which encapsulates the depth, stencil and accum
- * buffers and related parameters.
+ * A GLframebuffer is a structure which encapsulates the depth, stencil and
+ * accum buffers and related parameters.
  * 
  * \param visual a GLvisual pointer (we copy the struct contents)
  * \param softwareDepth create/use a software depth buffer?
@@ -699,12 +720,12 @@ _mesa_free_framebuffer_data( GLframebuffer *buffer )
 
 
 /**********************************************************************/
-/** \name Context allocation, initialization, destroying              */
-/**********************************************************************/
-/**
+/** \name Context allocation, initialization, destroying
+ *
  * The purpose of the most initalization functions here is to provide the
  * default state values according to the OpenGL specification.
  */
+/**********************************************************************/
 /*@{*/
 
 /**
@@ -717,7 +738,7 @@ _glthread_DECLARE_STATIC_MUTEX(OneTimeLock);
 /**
  * \brief Calls all the various one-time-init functions in Mesa.
  *
- * While holding the OneTimeLock lock, calls several initialization functions,
+ * While holding a global mutex lock, calls several initialization functions,
  * and sets the glapi callbacks if the \c MESA_DEBUG environment variable is
  * defined.
  *
@@ -1448,7 +1469,7 @@ _mesa_make_current2( GLcontext *newCtx, GLframebuffer *drawBuffer,
  * \return pointer to the current GL context.
  * 
  * Calls _glapi_get_context(). This isn't the fastest way to get the current
- * context.  If you need speed, see the GET_CURRENT_CONTEXT macro in context.h.
+ * context.  If you need speed, see the #GET_CURRENT_CONTEXT macro in context.h.
  */
 GLcontext *
 _mesa_get_current_context( void )
@@ -1478,7 +1499,7 @@ _mesa_get_dispatch(GLcontext *ctx)
 
 
 /**********************************************************************/
-/** \name Miscellaneous functions                     *****/
+/** \name Miscellaneous functions                                     */
 /**********************************************************************/
 /*@{*/
 
@@ -1513,7 +1534,7 @@ _mesa_record_error( GLcontext *ctx, GLenum error )
 /**
  * \brief Execute glFinish().
  *
- * Calls the ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH macro and the
+ * Calls the #ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH macro and the
  * dd_function_table::Finish driver callback, if not NULL.
  */
 void
@@ -1529,7 +1550,7 @@ _mesa_Finish( void )
 /**
  * \brief Execute glFlush().
  *
- * Calls the ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH macro and the
+ * Calls the #ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH macro and the
  * dd_function_table::Flush driver callback, if not NULL.
  */
 void
diff --git a/src/mesa/main/context.h b/src/mesa/main/context.h
index fbfd0a14929..4f6634265f0 100644
--- a/src/mesa/main/context.h
+++ b/src/mesa/main/context.h
@@ -43,7 +43,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: context.h,v 1.35.4.2 2003/03/22 16:49:58 jrfonseca Exp $ */
+/* $Id: context.h,v 1.35.4.3 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 #ifndef CONTEXT_H
 #define CONTEXT_H
@@ -170,9 +170,17 @@ _mesa_get_current_context(void);
 
 
 /**
- * \brief Macro for fetching the current context.
+ * \brief Macro for declaration and fetching the current context.
  *
- * It should be used in the variable declaration area of a function.
+ * \param C local variable which will hold the current context.
+ *
+ * It should be used in the variable declaration area of a function:
+ * \code
+ * ...
+ * {
+ *   GET_CURRENT_CONTEXT(ctx);
+ *   ...
+ * \endcode
  */
 #ifdef THREADS
 
diff --git a/src/mesa/main/dd.h b/src/mesa/main/dd.h
index f30e1421b8a..2efc27cb193 100644
--- a/src/mesa/main/dd.h
+++ b/src/mesa/main/dd.h
@@ -27,7 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: dd.h,v 1.74.6.5 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: dd.h,v 1.74.6.6 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 
 #ifndef DD_INCLUDED
@@ -128,8 +128,9 @@ struct dd_function_table {
    void (*Flush)( GLcontext *ctx );
 
    /**
-    * \brief Called whenever an error is generated.  ctx->ErrorValue contains
-    * the error value.
+    * \brief Called whenever an error is generated.  
+    *
+    * __GLcontextRec::ErrorValue contains the error value.
     */
    void (*Error)( GLcontext *ctx );
 
@@ -406,7 +407,7 @@ struct dd_function_table {
    /**
     * \brief Called by glCompressedTexImage2D().
     *
-    * \sa dd_function_table::glCompressedTexImage1D.
+    * \sa dd_function_table::CompressedTexImage1D.
     */
    void (*CompressedTexImage2D)( GLcontext *ctx, GLenum target,
                                  GLint level, GLint internalFormat,
@@ -417,7 +418,7 @@ struct dd_function_table {
    /**
     * \brief Called by glCompressedTexImage3D().
     *
-    * \sa dd_function_table::glCompressedTexImage3D.
+    * \sa dd_function_table::CompressedTexImage3D.
     */
    void (*CompressedTexImage3D)( GLcontext *ctx, GLenum target,
                                  GLint level, GLint internalFormat,
@@ -453,7 +454,7 @@ struct dd_function_table {
    /**
     * \brief Called by glCompressedTexSubImage2D().
     *
-    * \sa dd_function_table::glCompressedTexImage3D.
+    * \sa dd_function_table::CompressedTexImage3D.
     */
    void (*CompressedTexSubImage2D)(GLcontext *ctx, GLenum target, GLint level,
                                    GLint xoffset, GLint yoffset,
@@ -465,7 +466,7 @@ struct dd_function_table {
    /**
     * \brief Called by glCompressedTexSubImage3D().
     *
-    * \sa dd_function_table::glCompressedTexImage3D.
+    * \sa dd_function_table::CompressedTexImage3D.
     */
    void (*CompressedTexSubImage3D)(GLcontext *ctx, GLenum target, GLint level,
                                    GLint xoffset, GLint yoffset, GLint zoffset,
@@ -519,8 +520,8 @@ struct dd_function_table {
    /**
     * \brief Called when the texture's color lookup table is changed.
     * 
-    * If \p tObj is NULL then the shared texture palette ctx->Texture.Palette
-    * is to be updated.
+    * If \p tObj is NULL then the shared texture palette
+    * gl_texture_object::Palette is to be updated.
     */
    void (*UpdateTexturePalette)( GLcontext *ctx,
                                  struct gl_texture_object *tObj );
@@ -557,61 +558,100 @@ struct dd_function_table {
     * \note drawing functions are above.
     *
     * These functions are called by their corresponding OpenGL API functions.
-    * They're \e also called by the gl_PopAttrib() function!!!
+    * They are \e also called by the gl_PopAttrib() function!!!
     * May add more functions like these to the device driver in the future.
     */
    /*@{*/
+   /** \brief Specify the alpha test function */
    void (*AlphaFunc)(GLcontext *ctx, GLenum func, GLfloat ref);
+   /** \brief Set the blend color */
    void (*BlendColor)(GLcontext *ctx, const GLfloat color[4]);
+   /** \brief Set the blend equation */
    void (*BlendEquation)(GLcontext *ctx, GLenum mode);
+   /** \brief Specify pixel arithmetic */
    void (*BlendFunc)(GLcontext *ctx, GLenum sfactor, GLenum dfactor);
    void (*BlendFuncSeparate)(GLcontext *ctx,
                              GLenum sfactorRGB, GLenum dfactorRGB,
                              GLenum sfactorA, GLenum dfactorA);
+   /** \brief Specify clear values for the color buffers */
    void (*ClearColor)(GLcontext *ctx, const GLfloat color[4]);
+   /** \brief Specify the clear value for the depth buffer */
    void (*ClearDepth)(GLcontext *ctx, GLclampd d);
+   /** \brief Specify the clear value for the color index buffers */
    void (*ClearIndex)(GLcontext *ctx, GLuint index);
+   /** \brief Specify the clear value for the stencil buffer */
    void (*ClearStencil)(GLcontext *ctx, GLint s);
+   /** \brief Specify a plane against which all geometry is clipped */
    void (*ClipPlane)(GLcontext *ctx, GLenum plane, const GLfloat *equation );
+   /** \brief Enable and disable writing of frame buffer color components */
    void (*ColorMask)(GLcontext *ctx, GLboolean rmask, GLboolean gmask,
                      GLboolean bmask, GLboolean amask );
+   /** \brief Cause a material color to track the current color */
    void (*ColorMaterial)(GLcontext *ctx, GLenum face, GLenum mode);
+   /** \brief Specify whether front- or back-facing facets can be culled */
    void (*CullFace)(GLcontext *ctx, GLenum mode);
+   /** \brief Define front- and back-facing polygons */
    void (*FrontFace)(GLcontext *ctx, GLenum mode);
+   /** \brief Specify the value used for depth buffer comparisons */
    void (*DepthFunc)(GLcontext *ctx, GLenum func);
+   /** \brief Enable or disable writing into the depth buffer */
    void (*DepthMask)(GLcontext *ctx, GLboolean flag);
+   /** \brief Specify mapping of depth values from normalized device coordinates to window coordinates */
    void (*DepthRange)(GLcontext *ctx, GLclampd nearval, GLclampd farval);
+   /** \brief Enable or disable server-side gl capabilities */
    void (*Enable)(GLcontext *ctx, GLenum cap, GLboolean state);
+   /** \brief Specify fog parameters */
    void (*Fogfv)(GLcontext *ctx, GLenum pname, const GLfloat *params);
+   /** \brief Specify implementation-specific hints */
    void (*Hint)(GLcontext *ctx, GLenum target, GLenum mode);
+   /** \brief Control the writing of individual bits in the color index buffers */
    void (*IndexMask)(GLcontext *ctx, GLuint mask);
+   /** \brief Set light source parameters */
    void (*Lightfv)(GLcontext *ctx, GLenum light,
 		   GLenum pname, const GLfloat *params );
+   /** \brief Set the lighting model parameters */
    void (*LightModelfv)(GLcontext *ctx, GLenum pname, const GLfloat *params);
+   /** \brief Specify the line stipple pattern */
    void (*LineStipple)(GLcontext *ctx, GLint factor, GLushort pattern );
+   /** \brief Specify the width of rasterized lines */
    void (*LineWidth)(GLcontext *ctx, GLfloat width);
+   /** \brief Specify a logical pixel operation for color index rendering */
    void (*LogicOpcode)(GLcontext *ctx, GLenum opcode);
    void (*PointParameterfv)(GLcontext *ctx, GLenum pname,
                             const GLfloat *params);
+   /** \brief Specify the diameter of rasterized points */
    void (*PointSize)(GLcontext *ctx, GLfloat size);
+   /** \brief Select a polygon rasterization mode */
    void (*PolygonMode)(GLcontext *ctx, GLenum face, GLenum mode);
+   /** \brief Set the scale and units used to calculate depth values */
    void (*PolygonOffset)(GLcontext *ctx, GLfloat factor, GLfloat units);
+   /** \brief Set the polygon stippling pattern */
    void (*PolygonStipple)(GLcontext *ctx, const GLubyte *mask );
+   /** \brief Set rasterization mode */
    void (*RenderMode)(GLcontext *ctx, GLenum mode );
+   /** \brief Define the scissor box */
    void (*Scissor)(GLcontext *ctx, GLint x, GLint y, GLsizei w, GLsizei h);
+   /** \brief Select flat or smooth shading */
    void (*ShadeModel)(GLcontext *ctx, GLenum mode);
+   /** \brief Set function and reference value for stencil testing */
    void (*StencilFunc)(GLcontext *ctx, GLenum func, GLint ref, GLuint mask);
+   /** \brief Control the writing of individual bits in the stencil planes */
    void (*StencilMask)(GLcontext *ctx, GLuint mask);
+   /** \brief Set stencil test actions */
    void (*StencilOp)(GLcontext *ctx, GLenum fail, GLenum zfail, GLenum zpass);
    void (*ActiveStencilFace)(GLcontext *ctx, GLuint face);
+   /** \brief Control the generation of texture coordinates */
    void (*TexGen)(GLcontext *ctx, GLenum coord, GLenum pname,
 		  const GLfloat *params);
+   /** \brief Set texture environment parameters */
    void (*TexEnv)(GLcontext *ctx, GLenum target, GLenum pname,
                   const GLfloat *param);
+   /** \brief Set texture parameters */
    void (*TexParameter)(GLcontext *ctx, GLenum target,
                         struct gl_texture_object *texObj,
                         GLenum pname, const GLfloat *params);
    void (*TextureMatrix)(GLcontext *ctx, GLuint unit, const GLmatrix *mat);
+   /** \brief Set the viewport */
    void (*Viewport)(GLcontext *ctx, GLint x, GLint y, GLsizei w, GLsizei h);
    /*@}*/
 
@@ -648,10 +688,15 @@ struct dd_function_table {
     * Return GL_TRUE if query was completed, GL_FALSE otherwise.
     */
    /*@{*/
+   /** \brief Return the value or values of a selected parameter */
    GLboolean (*GetBooleanv)(GLcontext *ctx, GLenum pname, GLboolean *result);
+   /** \brief Return the value or values of a selected parameter */
    GLboolean (*GetDoublev)(GLcontext *ctx, GLenum pname, GLdouble *result);
+   /** \brief Return the value or values of a selected parameter */
    GLboolean (*GetFloatv)(GLcontext *ctx, GLenum pname, GLfloat *result);
+   /** \brief Return the value or values of a selected parameter */
    GLboolean (*GetIntegerv)(GLcontext *ctx, GLenum pname, GLint *result);
+   /** \brief Return the value or values of a selected parameter */
    GLboolean (*GetPointerv)(GLcontext *ctx, GLenum pname, GLvoid **result);
    /*@}*/
    
@@ -704,8 +749,9 @@ struct dd_function_table {
 #define FLUSH_STORED_VERTICES 0x1
 #define FLUSH_UPDATE_CURRENT  0x2
    /**
-    * Set by the driver-supplied T&L engine whenever vertices are
-    * buffered between glBegin()/glEnd() objects or ctx->Current is not uptodate.
+    * Set by the driver-supplied T&L engine whenever vertices are buffered
+    * between glBegin()/glEnd() objects or __GLcontextRec::Current is not
+    * uptodate.
     *
     * The dd_function_table::FlushVertices call below may be used to resolve
     * these conditions.
@@ -715,8 +761,8 @@ struct dd_function_table {
    /**
     * If inside glBegin()/glEnd(), it should ASSERT(0).  Otherwise, if
     * FLUSH_STORED_VERTICES bit in \p flags is set flushes any buffered
-    * vertices, if FLUSH_UPDATE_CURRENT bit is set updates ctx->Current and
-    * ctx->Light.Material
+    * vertices, if FLUSH_UPDATE_CURRENT bit is set updates
+    * __GLcontextRec::Current and gl_light_attrib::Material
     *
     * Note that the default T&L engine never clears the
     * FLUSH_UPDATE_CURRENT bit, even after performing the update.
diff --git a/src/mesa/main/debug.h b/src/mesa/main/debug.h
index 3295b0283c8..dea9ba3d61b 100644
--- a/src/mesa/main/debug.h
+++ b/src/mesa/main/debug.h
@@ -3,7 +3,7 @@
  * \brief Debugging functions.
  * 
  * \if subset
- * \brief (No-op.)
+ * \brief (No-op)
  *
  * \endif
  */
@@ -32,7 +32,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: debug.h,v 1.3.8.3 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: debug.h,v 1.3.8.4 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 
 #ifndef _DEBUG_H
@@ -49,16 +49,16 @@ extern void _mesa_check_driver_hooks( GLcontext *ctx );
 
 #else
 
-/** \brief No-op. */
+/** \brief No-op */
 #define _mesa_print_state( m, s ) ((void)0)
 
-/** \brief No-op. */
+/** \brief No-op */
 #define _mesa_print_info() ((void)0)
 
-/** \brief No-op. */
+/** \brief No-op */
 #define _mesa_init_debug( c ) ((void)0)
 
-/** \brief No-op. */
+/** \brief No-op */
 #define _mesa_check_driver_hooks( c ) ((void)0)
 
 #endif
diff --git a/src/mesa/main/depth.h b/src/mesa/main/depth.h
index fe2da33dd38..1a79603bccd 100644
--- a/src/mesa/main/depth.h
+++ b/src/mesa/main/depth.h
@@ -27,7 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: depth.h,v 1.11.8.3 2003/03/22 16:49:58 jrfonseca Exp $ */
+/* $Id: depth.h,v 1.11.8.4 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 
 #ifndef DEPTH_H
@@ -53,7 +53,7 @@ _mesa_init_depth( GLcontext * ctx );
 
 #else
 
-/** \brief No-op. */
+/** \brief No-op */
 #define _mesa_init_depth( c ) ((void)0)
 
 #endif
diff --git a/src/mesa/main/enums.h b/src/mesa/main/enums.h
index 5fa1cb10c0f..bc704027f30 100644
--- a/src/mesa/main/enums.h
+++ b/src/mesa/main/enums.h
@@ -3,7 +3,7 @@
  * \brief Enumeration name/number lookup functions.
  * 
  * \if subset
- * \brief (No-op.)
+ * \brief (No-op)
  *
  * \endif
  */
@@ -32,7 +32,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: enums.h,v 1.3.8.3 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: enums.h,v 1.3.8.4 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 
 #ifndef _ENUMS_H_
diff --git a/src/mesa/main/eval.h b/src/mesa/main/eval.h
index 76b71eae191..4c7b7bae8dd 100644
--- a/src/mesa/main/eval.h
+++ b/src/mesa/main/eval.h
@@ -3,7 +3,7 @@
  * \brief Eval operations.
  * 
  * \if subset
- * \brief (No-op.)
+ * \brief (No-op)
  *
  * \endif
  */
@@ -32,7 +32,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: eval.h,v 1.6.8.3 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: eval.h,v 1.6.8.4 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 
 #ifndef EVAL_H
diff --git a/src/mesa/main/extensions.h b/src/mesa/main/extensions.h
index 31658f03995..82f6e60eca8 100644
--- a/src/mesa/main/extensions.h
+++ b/src/mesa/main/extensions.h
@@ -3,7 +3,7 @@
  * \brief Extension handling.
  * 
  * \if subset
- * \brief (No-op.)
+ * \brief (No-op)
  *
  * \endif
  */
@@ -32,7 +32,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: extensions.h,v 1.15.6.2 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: extensions.h,v 1.15.6.3 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 
 #ifndef _EXTENSIONS_H_
diff --git a/src/mesa/main/feedback.c b/src/mesa/main/feedback.c
index ee406139982..29157af50da 100644
--- a/src/mesa/main/feedback.c
+++ b/src/mesa/main/feedback.c
@@ -27,7 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: feedback.c,v 1.27.4.4 2003/03/20 12:56:57 jrfonseca Exp $ */
+/* $Id: feedback.c,v 1.27.4.5 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 
 #include "glheader.h"
@@ -171,8 +171,8 @@ void _mesa_feedback_vertex( GLcontext *ctx,
  * 
  * \note this function can't be put in a display list.
  * 
- * Verifies we're not in GL_SELECT render mode, flushes the vertices and
- * initialize the fields in __GLcontextRec::Select with the given buffer.
+ * Verifies we're not in selection mode, flushes the vertices and initialize
+ * the fields in __GLcontextRec::Select with the given buffer.
  */
 void
 _mesa_SelectBuffer( GLsizei size, GLuint *buffer )
@@ -237,7 +237,7 @@ void _mesa_update_hitflag( GLcontext *ctx, GLfloat z )
  *
  * \param ctx GL context.
  *
- * Write the hit record, i.e., number of names in the stack, the minimum and
+ * Write the hit record, i.e., the number of names in the stack, the minimum and
  * maximum depth values and the number of names in the name stack at the time
  * of the event. Resets the hit flag. 
  *
@@ -417,8 +417,8 @@ _mesa_PopName( void )
  * Flushes the vertices and do the necessary cleanup according to the previous
  * rasterization mode, such as writing the hit record or resent the select
  * buffer index when exiting the select mode. Updates
- * __GLcontextRec::RenderMode and notifies the driver via
- * dd_function_table::RenderMode.
+ * __GLcontextRec::RenderMode and notifies the driver via the
+ * dd_function_table::RenderMode callback.
  */
 GLint
 _mesa_RenderMode( GLenum mode )
diff --git a/src/mesa/main/fog.h b/src/mesa/main/fog.h
index 85665c32151..da040668e5a 100644
--- a/src/mesa/main/fog.h
+++ b/src/mesa/main/fog.h
@@ -3,7 +3,7 @@
  * \brief Fog operations.
  * 
  * \if subset
- * \brief (No-op.)
+ * \brief (No-op)
  *
  * \endif
  */
@@ -32,7 +32,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: fog.h,v 1.12.8.2 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: fog.h,v 1.12.8.3 2003/03/23 23:22:47 jrfonseca Exp $ */
 
 
 #ifndef FOG_H
diff --git a/src/mesa/main/hash.c b/src/mesa/main/hash.c
index 29d505de12e..793bd9911a0 100644
--- a/src/mesa/main/hash.c
+++ b/src/mesa/main/hash.c
@@ -34,7 +34,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: hash.c,v 1.14.4.1 2003/03/16 00:27:12 jrfonseca Exp $ */
+/* $Id: hash.c,v 1.14.4.2 2003/03/23 23:22:48 jrfonseca Exp $ */
 
 #include "glheader.h"
 #include "imports.h"
@@ -149,7 +149,7 @@ void *_mesa_HashLookup(const struct _mesa_HashTable *table, GLuint key)
  * \param key the key (not zero).
  * \param data pointer to user data.
  *
- * While holding the hash table's lock, walk trhough the hash entry list replacing the data if a
+ * While holding the hash table's lock, walk through the hash entry list replacing the data if a
  * matching key is found, or inserts a new table entry otherwise.
  */
 void _mesa_HashInsert(struct _mesa_HashTable *table, GLuint key, void *data)
@@ -243,7 +243,7 @@ void _mesa_HashRemove(struct _mesa_HashTable *table, GLuint key)
  * 
  * \return key for the "first" entry in the hash table.
  *
- * While holding the lock, walks trhough all table positions until returning
+ * While holding the lock, walks through all table positions until finding
  * the first entry of the first non-empty one.
  */
 GLuint _mesa_HashFirstEntry(struct _mesa_HashTable *table)
@@ -291,7 +291,10 @@ void _mesa_HashPrint(const struct _mesa_HashTable *table)
  * 
  * \return Starting key of free block or 0 if failure.
  *
- * If there are enough free keys between the maximum key existing in the table (_mesa_HashTable::MaxKey) and the maximum key possible, then simply return the adjacent key. Otherwise do a full search for a free key block in the existing key range.
+ * If there are enough free keys between the maximum key existing in the table
+ * (_mesa_HashTable::MaxKey) and the maximum key possible, then simply return
+ * the adjacent key. Otherwise do a full search for a free key block in the
+ * allowable key range.
  */
 GLuint _mesa_HashFindFreeKeyBlock(struct _mesa_HashTable *table, GLuint numKeys)
 {
diff --git a/src/mesa/main/hint.h b/src/mesa/main/hint.h
index 9ab1d6bfe5e..36198d02e77 100644
--- a/src/mesa/main/hint.h
+++ b/src/mesa/main/hint.h
@@ -3,7 +3,7 @@
  * \brief Hints operations.
  * 
  * \if subset
- * \brief (No-op.)
+ * \brief (No-op)
  *
  * \endif
  */
@@ -32,7 +32,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: hint.h,v 1.4.6.2 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: hint.h,v 1.4.6.3 2003/03/23 23:22:48 jrfonseca Exp $ */
 
 
 #ifndef HINT_H
diff --git a/src/mesa/main/histogram.h b/src/mesa/main/histogram.h
index dd77a51e93c..6df9f8f3cd9 100644
--- a/src/mesa/main/histogram.h
+++ b/src/mesa/main/histogram.h
@@ -3,7 +3,7 @@
  * \brief Histogram.
  * 
  * \if subset
- * \brief (No-op.)
+ * \brief (No-op)
  *
  * \endif
  */
@@ -32,7 +32,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: histogram.h,v 1.4.4.3 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: histogram.h,v 1.4.4.4 2003/03/23 23:22:48 jrfonseca Exp $ */
 
 
 #ifndef HISTOGRAM_H
diff --git a/src/mesa/main/image.c b/src/mesa/main/image.c
index 46e51933d83..4b5182bcb4b 100644
--- a/src/mesa/main/image.c
+++ b/src/mesa/main/image.c
@@ -27,7 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: image.c,v 1.69.4.4 2003/03/20 12:56:57 jrfonseca Exp $ */
+/* $Id: image.c,v 1.69.4.5 2003/03/23 23:22:48 jrfonseca Exp $ */
 
 
 #include "glheader.h"
@@ -441,7 +441,7 @@ _mesa_is_legal_format_and_type( GLenum format, GLenum type )
 /**
  * \brief Get the address of a pixel in an image (actually a volume).
  *
- * Pixel unpacking/packing parameters are observed according to 'packing'.
+ * Pixel unpacking/packing parameters are observed according to \p packing.
  *
  * \param image start of image data.
  * \param width image width.
diff --git a/src/mesa/main/lines.c b/src/mesa/main/lines.c
index eddaf2a20ed..d42c2d58472 100644
--- a/src/mesa/main/lines.c
+++ b/src/mesa/main/lines.c
@@ -27,7 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: lines.c,v 1.30.4.2 2003/03/20 19:38:40 jrfonseca Exp $ */
+/* $Id: lines.c,v 1.30.4.3 2003/03/23 23:22:48 jrfonseca Exp $ */
 
 
 #include "glheader.h"
@@ -50,8 +50,8 @@
  * Verifies the parameter and updates gl_line_attrib::Width. On a change,
  * flushes the vertices, updates the clamped line width and marks the
  * DD_LINE_WIDTH flag in __GLcontextRec::_TriangleCaps for the drivers if the
- * width is different from one . Notifies the driver via
- * dd_function_table::LineWidth.
+ * width is different from one. Notifies the driver via the
+ * dd_function_table::LineWidth callback.
  */
 void
 _mesa_LineWidth( GLfloat width )
@@ -94,7 +94,7 @@ _mesa_LineWidth( GLfloat width )
  *
  * Updates gl_line_attrib::StippleFactor and gl_line_attrib::StipplePattern. On
  * change flushes the vertices and notifies the driver via
- * dd_function_table::LineStipple.
+ * the dd_function_table::LineStipple callback.
  */
 void
 _mesa_LineStipple( GLint factor, GLushort pattern )
diff --git a/src/mesa/main/matrix.c b/src/mesa/main/matrix.c
index c28f847299b..1f97cedd004 100644
--- a/src/mesa/main/matrix.c
+++ b/src/mesa/main/matrix.c
@@ -32,7 +32,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: matrix.c,v 1.45.4.6 2003/03/23 14:58:08 jrfonseca Exp $ */
+/* $Id: matrix.c,v 1.45.4.7 2003/03/23 23:22:48 jrfonseca Exp $ */
 
 
 #include "glheader.h"
@@ -141,7 +141,7 @@ _mesa_Ortho( GLdouble left, GLdouble right,
  * \sa glMatrixMode().
  *
  * Flushes the vertices, validates the parameter and updates
- * __GLcontextRec::CurrentStack and __GLcontextRec::MatrixMode with the
+ * __GLcontextRec::CurrentStack and gl_transform_attrib::MatrixMode with the
  * specified matrix stack.
  */
 void
@@ -196,7 +196,7 @@ _mesa_MatrixMode( GLenum mode )
  * \sa glPushMatrix().
  * 
  * Verifies the current matrix stack is not full, and duplicates the top-most
- * matrix in the stack. Marks __GLcontexRec::NewState with the stack dirty
+ * matrix in the stack. Marks __GLcontextRec::NewState with the stack dirty
  * flag.
  */
 void
@@ -228,8 +228,8 @@ _mesa_PushMatrix( void )
  * \sa glPopMatrix().
  * 
  * Flushes the vertices, verifies the current matrix stack is not empty, and
- * moves the stack head down. Marks __GLcontexRec::NewState with the stack
- * dirty flag.
+ * moves the stack head down. Marks __GLcontextRec::NewState with the dirty
+ * stack flag.
  */
 void
 _mesa_PopMatrix( void )
@@ -258,7 +258,7 @@ _mesa_PopMatrix( void )
  * \sa glLoadIdentity().
  *
  * Flushes the vertices and calls _math_matrix_set_identity() with the top-most
- * matrix in the current stack. Marks __GLcontexRec::NewState with the stack
+ * matrix in the current stack. Marks __GLcontextRec::NewState with the stack
  * dirty flag.
  */
 void
@@ -283,8 +283,8 @@ _mesa_LoadIdentity( void )
  * \sa glLoadMatrixf().
  *
  * Flushes the vertices and calls _math_matrix_loadf() with the top-most matrix
- * in the current stack and the given matrix. Marks __GLcontexRec::NewState
- * with the stack dirty flag.
+ * in the current stack and the given matrix. Marks __GLcontextRec::NewState
+ * with the dirty stack flag.
  */
 void
 _mesa_LoadMatrixf( const GLfloat *m )
@@ -314,7 +314,7 @@ _mesa_LoadMatrixf( const GLfloat *m )
  *
  * Flushes the vertices and calls _math_matrix_mul_floats() with the top-most
  * matrix in the current stack and the given matrix. Marks
- * __GLcontexRec::NewState with the stack dirty flag.
+ * __GLcontextRec::NewState with the dirty stack flag.
  */
 void
 _mesa_MultMatrixf( const GLfloat *m )
@@ -346,7 +346,7 @@ _mesa_MultMatrixf( const GLfloat *m )
  *
  * Flushes the vertices and calls _math_matrix_rotate() with the top-most
  * matrix in the current stack and the given parameters. Marks
- * __GLcontexRec::NewState with the stack dirty flag.
+ * __GLcontextRec::NewState with the dirty stack flag.
  */
 void
 _mesa_Rotatef( GLfloat angle, GLfloat x, GLfloat y, GLfloat z )
@@ -371,7 +371,7 @@ _mesa_Rotatef( GLfloat angle, GLfloat x, GLfloat y, GLfloat z )
  *
  * Flushes the vertices and calls _math_matrix_scale() with the top-most
  * matrix in the current stack and the given parameters. Marks
- * __GLcontexRec::NewState with the stack dirty flag.
+ * __GLcontextRec::NewState with the dirty stack flag.
  */
 void
 _mesa_Scalef( GLfloat x, GLfloat y, GLfloat z )
@@ -394,7 +394,7 @@ _mesa_Scalef( GLfloat x, GLfloat y, GLfloat z )
  *
  * Flushes the vertices and calls _math_matrix_translate() with the top-most
  * matrix in the current stack and the given parameters. Marks
- * __GLcontexRec::NewState with the stack dirty flag.
+ * __GLcontextRec::NewState with the dirty stack flag.
  */
 void
 _mesa_Translatef( GLfloat x, GLfloat y, GLfloat z )
@@ -526,7 +526,8 @@ _mesa_Viewport( GLint x, GLint y, GLsizei width, GLsizei height )
  *
  * Verifies the parameters, clamps them to the implementation dependent range
  * and updates __GLcontextRec::Viewport. Computes the scale and bias values for
- * the drivers and notifies the driver via dd_function_table::Viewport.
+ * the drivers and notifies the driver via the dd_function_table::Viewport
+ * callback.
  */
 void
 _mesa_set_viewport( GLcontext *ctx, GLint x, GLint y,
diff --git a/src/mesa/main/mtypes.h b/src/mesa/main/mtypes.h
index c46aa3441eb..91e79c01fd4 100644
--- a/src/mesa/main/mtypes.h
+++ b/src/mesa/main/mtypes.h
@@ -29,7 +29,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: mtypes.h,v 1.97.4.8 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: mtypes.h,v 1.97.4.9 2003/03/23 23:22:48 jrfonseca Exp $ */
 
 
 #ifndef TYPES_H
@@ -178,7 +178,7 @@ enum {
 
 
 /**
- * Maximum number of temporary vertices required for clipping.  
+ * \brief Maximum number of temporary vertices required for clipping.  
  *
  * Used in array_cache and tnl modules.
  */
@@ -203,9 +203,11 @@ struct gl_color_table {
 };
 
 
-/*
- * Bit flags used for updating material values.
+/**
+ * \name Bit flags used for updating material values.
+ * .
  */
+/*@{*/
 #define FRONT_AMBIENT_BIT     0x1
 #define BACK_AMBIENT_BIT      0x2
 #define FRONT_DIFFUSE_BIT     0x4
@@ -228,8 +230,7 @@ struct gl_color_table {
 				 BACK_SHININESS_BIT | BACK_INDEXES_BIT)
 
 #define ALL_MATERIAL_BITS	(FRONT_MATERIAL_BITS | BACK_MATERIAL_BITS)
-
-
+/*@}*/
 
 
 #define EXP_TABLE_SIZE 512	/**< \brief Specular exponent lookup table sizes */
@@ -324,9 +325,13 @@ struct gl_accum_attrib {
 };
 
 
-/*
- * Used in _DrawDestMask and _ReadSrcMask below to identify color buffers.
+/**
+ * \name Clipping planes bits
+ * 
+ * Used in gl_colorbuffer_attrib::_DrawDestMask and
+ * gl_colorbuffer_attrib::_ReadSrcMask below to identify color buffers.
  */
+/*@{*/
 #define FRONT_LEFT_BIT  0x1
 #define FRONT_RIGHT_BIT 0x2
 #define BACK_LEFT_BIT   0x4
@@ -335,6 +340,7 @@ struct gl_accum_attrib {
 #define AUX1_BIT        0x20
 #define AUX2_BIT        0x40
 #define AUX3_BIT        0x80
+/*@}*/
 
 
 /**
@@ -347,8 +353,8 @@ struct gl_colorbuffer_attrib {
    GLuint IndexMask;			/**< \brief Color index write mask */
    GLubyte ColorMask[4];		/**< \brief Each flag is 0xff or 0x0 */
 
-   GLenum DrawBuffer;		/**< \brief Which buffer to draw into */
-   GLubyte _DrawDestMask;	/**< \brief bitwise-OR of FRONT/BACK_LEFT/RIGHT_BITs */
+   GLenum DrawBuffer;			/**< \brief Which buffer to draw into */
+   GLubyte _DrawDestMask;		/**< \brief bitwise-OR of FRONT/BACK_LEFT/RIGHT_BITs */
 
    /** 
     * \name alpha testing
@@ -356,11 +362,11 @@ struct gl_colorbuffer_attrib {
    /*@{*/
    GLboolean AlphaEnabled;		/**< \brief Alpha test enabled flag */
    GLenum AlphaFunc;			/**< \brief Alpha test function */
-   GLclampf AlphaRef;
+   GLclampf AlphaRef;			/**< \brief Alpha reference value */
    /*@}*/
 
    /** 
-    * \name blending
+    * \name Blending
     */
    /*@{*/
    GLboolean BlendEnabled;		/**< \brief Blending enabled flag */
@@ -368,12 +374,12 @@ struct gl_colorbuffer_attrib {
    GLenum BlendDstRGB;			/**< \brief Blending destination operator */
    GLenum BlendSrcA;			/**< \brief GL_INGR_blend_func_separate */
    GLenum BlendDstA;			/**< \brief GL_INGR_blend_func_separate */
-   GLenum BlendEquation;
-   GLfloat BlendColor[4];
+   GLenum BlendEquation;		/**< \brief Blending equation */
+   GLfloat BlendColor[4];		/**< \brief Bleding color */
    /*@}*/
 
    /** 
-    * \name logic op
+    * \name Logic op
     */
    /*@{*/
    GLenum LogicOp;			/**< \brief Logic operator */
@@ -613,6 +619,9 @@ struct gl_convolution_attrib {
 #define LIGHT_POSITIONAL   0x4
 #define LIGHT_NEED_VERTICES (LIGHT_POSITIONAL|LIGHT_LOCAL_VIEWER)
 
+/**
+ * \brief Lighting attributes.
+ */
 struct gl_light_attrib {
    struct gl_light Light[MAX_LIGHTS];	/**< \brief Array of lights */
    struct gl_lightmodel Model;		/**< \brief Lighting model */
@@ -691,8 +700,9 @@ struct gl_multisample_attrib {
  * \brief Pixel attributes.
  */
 struct gl_pixel_attrib {
-   GLenum ReadBuffer;		/**< \brief src buffer for glRead/CopyPixels */
+   GLenum ReadBuffer;		/**< \brief source buffer for glReadPixels()/glCopyPixels() */
    GLubyte _ReadSrcMask;	/**< \brief Not really a mask, but like _DrawDestMask
+				  *
 				  * May be: FRONT_LEFT_BIT, BACK_LEFT_BIT,
 				  * FRONT_RIGHT_BIT or BACK_RIGHT_BIT. */
    GLfloat RedBias, RedScale;
@@ -1039,7 +1049,9 @@ struct gl_texture_object {
 };
 
 
-/* Texture unit record */
+/**
+ * \brief Texture unit record 
+ */
 struct gl_texture_unit {
    GLuint Enabled;              /**< \brief bitmask of TEXTURE_*_BIT flags */
    GLuint _ReallyEnabled;       /**< \brief 0 or exactly one of TEXTURE_*_BIT flags */
@@ -1136,7 +1148,7 @@ struct gl_texture_attrib {
  */
 struct gl_transform_attrib {
    GLenum MatrixMode;				/**< \brief Matrix mode */
-   GLfloat EyeUserPlane[MAX_CLIP_PLANES][4];
+   GLfloat EyeUserPlane[MAX_CLIP_PLANES][4];	/**< \brief User clip planes */
    GLfloat _ClipUserPlane[MAX_CLIP_PLANES][4];	/**< \brief derived */
    GLuint ClipPlanesEnabled;                    /**< \brief on/off bitmask */
    GLboolean Normalize;				/**< \brief Normalize all normals? */
@@ -1413,14 +1425,14 @@ struct vp_instruction
  */
 struct vp_program
 {
-   GLubyte *String;                      /**< \brief Original user code */
-   struct vp_instruction *Instructions;  /**< \brief Compiled instructions */
-   GLenum Target;      /**< \brief GL_VERTEX_PROGRAM_NV or GL_VERTEX_STATE_PROGRAM_NV */
-   GLint RefCount;            /**< \brief Since programs can be shared among contexts */
-   GLboolean IsPositionInvariant;  /**< \brief GL_NV_vertex_program1_1 */
+   GLubyte *String;                     /**< \brief Original user code */
+   struct vp_instruction *Instructions;	/**< \brief Compiled instructions */
+   GLenum Target;      			/**< \brief GL_VERTEX_PROGRAM_NV or GL_VERTEX_STATE_PROGRAM_NV */
+   GLint RefCount;            		/**< \brief Since programs can be shared among contexts */
+   GLboolean IsPositionInvariant;	/**< \brief GL_NV_vertex_program1_1 */
    GLboolean Resident;
-   GLuint InputsRead;     /**< \brief Bitmask of which input regs are read */
-   GLuint OutputsWritten; /**< \brief Bitmask of which output regs are written to */
+   GLuint InputsRead;			/**< \brief Bitmask of which input regs are read */
+   GLuint OutputsWritten;		/**< \brief Bitmask of which output regs are written to */
 };
 
 
@@ -1654,9 +1666,12 @@ struct matrix_stack
 };
 
 
-/*
- * Bits for image transfer operations (ctx->ImageTransferState).
+/**
+ * \name Bits for image transfer operations 
+ *
+ * \sa __GLcontextRec::ImageTransferState.
  */
+/*@{*/
 #define IMAGE_SCALE_BIAS_BIT                      0x1
 #define IMAGE_SHIFT_OFFSET_BIT                    0x2
 #define IMAGE_MAP_COLOR_BIT                       0x4
@@ -1669,58 +1684,66 @@ struct matrix_stack
 #define IMAGE_HISTOGRAM_BIT                       0x200
 #define IMAGE_MIN_MAX_BIT                         0x400
 
-/** transfer ops up to convolution: */
+/** \brief Transfer ops up to convolution */
 #define IMAGE_PRE_CONVOLUTION_BITS (IMAGE_SCALE_BIAS_BIT |     \
                                     IMAGE_SHIFT_OFFSET_BIT |   \
                                     IMAGE_MAP_COLOR_BIT |      \
                                     IMAGE_COLOR_TABLE_BIT)
 
-/** transfer ops after convolution: */
+/** \brief Ttransfer ops after convolution */
 #define IMAGE_POST_CONVOLUTION_BITS (IMAGE_POST_CONVOLUTION_SCALE_BIAS |      \
                                      IMAGE_POST_CONVOLUTION_COLOR_TABLE_BIT | \
                                      IMAGE_COLOR_MATRIX_BIT |                 \
                                      IMAGE_POST_COLOR_MATRIX_COLOR_TABLE_BIT |\
                                      IMAGE_HISTOGRAM_BIT |                    \
                                      IMAGE_MIN_MAX_BIT)
+/*@}*/
 
 
-/*
- * Bits to indicate what state has changed.  6 unused flags.
- */
-#define _NEW_MODELVIEW		0x1        /**< \brief ctx->ModelView */
-#define _NEW_PROJECTION		0x2        /**< \brief ctx->Projection */
-#define _NEW_TEXTURE_MATRIX	0x4        /**< \brief ctx->TextureMatrix */
-#define _NEW_COLOR_MATRIX	0x8        /**< \brief ctx->ColorMatrix */
-#define _NEW_ACCUM		0x10       /**< \brief ctx->Accum */
-#define _NEW_COLOR		0x20       /**< \brief ctx->Color */
-#define _NEW_DEPTH		0x40       /**< \brief ctx->Depth */
-#define _NEW_EVAL		0x80       /**< \brief ctx->Eval, ctx->EvalMap */
-#define _NEW_FOG		0x100      /**< \brief ctx->Fog */
-#define _NEW_HINT		0x200      /**< \brief ctx->Hint */
-#define _NEW_LIGHT		0x400      /**< \brief ctx->Light */
-#define _NEW_LINE		0x800      /**< \brief ctx->Line */
-#define _NEW_PIXEL		0x1000     /**< \brief ctx->Pixel */
-#define _NEW_POINT		0x2000     /**< \brief ctx->Point */
-#define _NEW_POLYGON		0x4000     /**< \brief ctx->Polygon */
-#define _NEW_POLYGONSTIPPLE	0x8000     /**< \brief ctx->PolygonStipple */
-#define _NEW_SCISSOR		0x10000    /**< \brief ctx->Scissor */
-#define _NEW_STENCIL		0x20000    /**< \brief ctx->Stencil */
-#define _NEW_TEXTURE		0x40000    /**< \brief ctx->Texture */
-#define _NEW_TRANSFORM		0x80000    /**< \brief ctx->Transform */
-#define _NEW_VIEWPORT		0x100000   /**< \brief ctx->Viewport */
-#define _NEW_PACKUNPACK		0x200000   /**< \brief ctx->Pack, ctx->Unpack */
-#define _NEW_ARRAY	        0x400000   /**< \brief ctx->Array */
-#define _NEW_RENDERMODE		0x800000   /**< \brief RenderMode, Feedback, Select */
-#define _NEW_BUFFERS            0x1000000  /**< \brief ctx->Visual, ctx->DrawBuffer, */
-#define _NEW_MULTISAMPLE        0x2000000  /**< \brief ctx->Multisample */
-#define _NEW_TRACK_MATRIX       0x4000000  /**< \brief ctx->VertexProgram */
-#define _NEW_PROGRAM            0x8000000  /**< \brief ctx->VertexProgram */
+/**
+ * \name Bits to indicate what state has changed.  
+ *
+ * 6 unused flags.
+ */
+/*@{*/
+#define _NEW_MODELVIEW		0x1        /**< \brief __GLcontextRec::ModelView */
+#define _NEW_PROJECTION		0x2        /**< \brief __GLcontextRec::Projection */
+#define _NEW_TEXTURE_MATRIX	0x4        /**< \brief __GLcontextRec::TextureMatrix */
+#define _NEW_COLOR_MATRIX	0x8        /**< \brief __GLcontextRec::ColorMatrix */
+#define _NEW_ACCUM		0x10       /**< \brief __GLcontextRec::Accum */
+#define _NEW_COLOR		0x20       /**< \brief __GLcontextRec::Color */
+#define _NEW_DEPTH		0x40       /**< \brief __GLcontextRec::Depth */
+#define _NEW_EVAL		0x80       /**< \brief __GLcontextRec::Eval, __GLcontextRec::EvalMap */
+#define _NEW_FOG		0x100      /**< \brief __GLcontextRec::Fog */
+#define _NEW_HINT		0x200      /**< \brief __GLcontextRec::Hint */
+#define _NEW_LIGHT		0x400      /**< \brief __GLcontextRec::Light */
+#define _NEW_LINE		0x800      /**< \brief __GLcontextRec::Line */
+#define _NEW_PIXEL		0x1000     /**< \brief __GLcontextRec::Pixel */
+#define _NEW_POINT		0x2000     /**< \brief __GLcontextRec::Point */
+#define _NEW_POLYGON		0x4000     /**< \brief __GLcontextRec::Polygon */
+#define _NEW_POLYGONSTIPPLE	0x8000     /**< \brief __GLcontextRec::PolygonStipple */
+#define _NEW_SCISSOR		0x10000    /**< \brief __GLcontextRec::Scissor */
+#define _NEW_STENCIL		0x20000    /**< \brief __GLcontextRec::Stencil */
+#define _NEW_TEXTURE		0x40000    /**< \brief __GLcontextRec::Texture */
+#define _NEW_TRANSFORM		0x80000    /**< \brief __GLcontextRec::Transform */
+#define _NEW_VIEWPORT		0x100000   /**< \brief __GLcontextRec::Viewport */
+#define _NEW_PACKUNPACK		0x200000   /**< \brief __GLcontextRec::Pack, __GLcontextRec::Unpack */
+#define _NEW_ARRAY	        0x400000   /**< \brief __GLcontextRec::Array */
+#define _NEW_RENDERMODE		0x800000   /**< \brief __GLcontextRec::RenderMode, __GLcontextRec::Feedback, __GLcontextRec::Select */
+#define _NEW_BUFFERS            0x1000000  /**< \brief __GLcontextRec::Visual, __GLcontextRec::DrawBuffer, */
+#define _NEW_MULTISAMPLE        0x2000000  /**< \brief __GLcontextRec::Multisample */
+#define _NEW_TRACK_MATRIX       0x4000000  /**< \brief __GLcontextRec::VertexProgram */
+#define _NEW_PROGRAM            0x8000000  /**< \brief __GLcontextRec::VertexProgram */
 #define _NEW_ALL ~0
+/*@}*/
 
 
-
-/* Bits to track array state changes (also used to summarize array enabled)
+/**
+ * \name Bits to track array state changes 
+ *
+ * Also used to summarize array enabled.
  */
+/*@{*/
 #define _NEW_ARRAY_VERTEX           VERT_BIT_POS
 #define _NEW_ARRAY_WEIGHT           VERT_BIT_WEIGHT
 #define _NEW_ARRAY_NORMAL           VERT_BIT_NORMAL
@@ -1743,11 +1766,15 @@ struct matrix_stack
 
 #define _NEW_ARRAY_TEXCOORD(i) (_NEW_ARRAY_TEXCOORD_0 << (i))
 #define _NEW_ARRAY_ATTRIB(i) (_NEW_ARRAY_ATTRIB_0 << (i))
+/*@}*/
 
 
-/* A bunch of flags that we think might be useful to drivers.
- * Set in the ctx->_TriangleCaps bitfield.
+/**
+ * \name A bunch of flags that we think might be useful to drivers.
+ * 
+ * Set in the __GLcontextRec::_TriangleCaps bitfield.
  */
+/*@{*/
 #define DD_FLATSHADE                0x1
 #define DD_SEPARATE_SPECULAR        0x2
 #define DD_TRI_CULL_FRONT_BACK      0x4 /* special case on some hw */
@@ -1762,10 +1789,13 @@ struct matrix_stack
 #define DD_POINT_SMOOTH             0x800
 #define DD_POINT_SIZE               0x1000
 #define DD_POINT_ATTEN              0x2000
+/*@}*/
 
 
-/* Define the state changes under which each of these bits might change
+/**
+ * \name Define the state changes under which each of these bits might change
  */
+/*@{*/
 #define _DD_NEW_FLATSHADE                _NEW_LIGHT
 #define _DD_NEW_SEPARATE_SPECULAR        (_NEW_LIGHT | _NEW_FOG)
 #define _DD_NEW_TRI_CULL_FRONT_BACK      _NEW_POLYGON
@@ -1780,6 +1810,8 @@ struct matrix_stack
 #define _DD_NEW_POINT_SMOOTH             _NEW_POINT
 #define _DD_NEW_POINT_SIZE               _NEW_POINT
 #define _DD_NEW_POINT_ATTEN              _NEW_POINT
+/*@}*/
+
 
 #define _MESA_NEW_NEED_EYE_COORDS         (_NEW_LIGHT |		\
                                            _NEW_TEXTURE |	\
@@ -1792,12 +1824,17 @@ struct matrix_stack
 #define _IMAGE_NEW_TRANSFER_STATE         (_NEW_PIXEL | _NEW_COLOR_MATRIX)
 
 
-/* Bits for ctx->_NeedEyeCoords */
+/**
+ * \name Bits for __GLcontextRec::_NeedEyeCoords.
+ * .
+ */
+/*@{*/
 #define NEED_EYE_TEXGEN          0x1
 #define NEED_EYE_LIGHT           0x2
 #define NEED_EYE_LIGHT_MODELVIEW 0x4
 #define NEED_EYE_POINT_ATTEN     0x8
 #define NEED_EYE_DRIVER          0x10
+/*@}*/
 
 
 /*
@@ -2097,7 +2134,17 @@ enum _debug {
 #define Elements(x) sizeof(x)/sizeof(*(x))
 
 
-/* Eventually let the driver specify what statechanges require a flush:
+/**
+ * \brief Flush vertices.
+ *
+ * \param ctx GL context.
+ * \param newstate new state.
+ *
+ * Checks if dd_function_table::NeedFlush is marked to flush stored vertices,
+ * and calls dd_function_table::FlushVertices if so. Marks
+ * __GLcontextRec::NewState with \p newstate.
+ * 
+ * \todo Eventually let the driver specify what statechanges require a flush:
  */
 #define FLUSH_VERTICES(ctx, newstate)				\
 do {								\
@@ -2108,6 +2155,16 @@ do {								\
    ctx->NewState |= newstate;					\
 } while (0)
 
+/**
+ * \brief Flush current state.
+ *
+ * \param ctx GL context.
+ * \param newstate new state.
+ *
+ * Checks if dd_function_table::NeedFlush is marked to flush current state,
+ * and calls dd_function_table::FlushVertices if so. Marks
+ * __GLcontextRec::NewState with \p newstate.
+ */
 #define FLUSH_CURRENT(ctx, newstate)				\
 do {								\
    if (MESA_VERBOSE & VERBOSE_STATE)				\
@@ -2117,6 +2174,13 @@ do {								\
    ctx->NewState |= newstate;					\
 } while (0)
 
+/**
+ * \brief Macro to assert that the API call was made outside the
+ * glBegin()/glEnd() pair, with return value.
+ * 
+ * \param ctx GL context.
+ * \param retval value to return value in case the assertation fails.
+ */
 #define ASSERT_OUTSIDE_BEGIN_END_WITH_RETVAL(ctx, retval)		\
 do {									\
    if (ctx->Driver.CurrentExecPrimitive != PRIM_OUTSIDE_BEGIN_END) {	\
@@ -2125,6 +2189,12 @@ do {									\
    }									\
 } while (0)
 
+/**
+ * \brief Macro to assert that the API call was made outside the
+ * glBegin()/glEnd() pair.
+ * 
+ * \param ctx GL context.
+ */
 #define ASSERT_OUTSIDE_BEGIN_END(ctx)					\
 do {									\
    if (ctx->Driver.CurrentExecPrimitive != PRIM_OUTSIDE_BEGIN_END) {	\
@@ -2133,12 +2203,26 @@ do {									\
    }									\
 } while (0)
 
+/**
+ * \brief Macro to assert that the API call was made outside the
+ * glBegin()/glEnd() pair and flush the vertices.
+ * 
+ * \param ctx GL context.
+ * \param retval value to return value in case the assertation fails.
+ */
 #define ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH(ctx)				\
 do {									\
    ASSERT_OUTSIDE_BEGIN_END(ctx);					\
    FLUSH_VERTICES(ctx, 0);						\
 } while (0)
 
+/**
+ * \brief Macro to assert that the API call was made outside the
+ * glBegin()/glEnd() pair and flush the vertices, with return value.
+ * 
+ * \param ctx GL context.
+ * \param retval value to return value in case the assertation fails.
+ */
 #define ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH_WITH_RETVAL(ctx, retval)	\
 do {									\
    ASSERT_OUTSIDE_BEGIN_END_WITH_RETVAL(ctx, retval);			\
@@ -2146,6 +2230,4 @@ do {									\
 } while (0)
 
 
-
-
 #endif /* TYPES_H */
diff --git a/src/mesa/main/points.c b/src/mesa/main/points.c
index 40944f28e12..c6879b7ec8e 100644
--- a/src/mesa/main/points.c
+++ b/src/mesa/main/points.c
@@ -27,7 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: points.c,v 1.34.4.3 2003/03/20 19:38:43 jrfonseca Exp $ */
+/* $Id: points.c,v 1.34.4.4 2003/03/23 23:22:48 jrfonseca Exp $ */
 
 
 #include "glheader.h"
@@ -50,7 +50,7 @@
  * flushes the vertices, updates the clamped point size and marks the
  * DD_POINT_SIZE flag in __GLcontextRec::_TriangleCaps for the drivers if the
  * size is different from one. Notifies the driver via
- * dd_function_table::PointSize.
+ * the dd_function_table::PointSize callback.
  */
 void
 _mesa_PointSize( GLfloat size )
diff --git a/src/mesa/main/polygon.c b/src/mesa/main/polygon.c
index 85d916fcf75..f8c36f41159 100644
--- a/src/mesa/main/polygon.c
+++ b/src/mesa/main/polygon.c
@@ -27,7 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: polygon.c,v 1.25.4.4 2003/03/20 19:38:46 jrfonseca Exp $ */
+/* $Id: polygon.c,v 1.25.4.5 2003/03/23 23:22:48 jrfonseca Exp $ */
 
 
 #include "glheader.h"
@@ -49,7 +49,7 @@
  *
  * Verifies the parameter and updates gl_polygon_attrib::CullFaceMode. On
  * change, flushes the vertices and notifies the driver via
- * dd_function_table::CullFace.
+ * the dd_function_table::CullFace callback.
  */
 void
 _mesa_CullFace( GLenum mode )
@@ -85,7 +85,7 @@ _mesa_CullFace( GLenum mode )
  *
  * Verifies the parameter and updates gl_polygon_attrib::FrontFace. On change
  * flushes the vertices and notifies the driver via
- * dd_function_table::FrontFace.
+ * the dd_function_table::FrontFace callback.
  */
 void
 _mesa_FrontFace( GLenum mode )
@@ -124,7 +124,7 @@ _mesa_FrontFace( GLenum mode )
  * 
  * Verifies the parameters and updates gl_polygon_attrib::FrontMode and
  * gl_polygon_attrib::BackMode. On change flushes the vertices and notifies the
- * driver via dd_function_table::PolygonMode.
+ * driver via the dd_function_table::PolygonMode callback.
  */
 void
 _mesa_PolygonMode( GLenum face, GLenum mode )
diff --git a/src/mesa/main/stencil.c b/src/mesa/main/stencil.c
index 47a98acdb88..28fb1bfbc00 100644
--- a/src/mesa/main/stencil.c
+++ b/src/mesa/main/stencil.c
@@ -27,7 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: stencil.c,v 1.29.4.3 2003/03/20 19:38:47 jrfonseca Exp $ */
+/* $Id: stencil.c,v 1.29.4.4 2003/03/23 23:22:48 jrfonseca Exp $ */
 
 
 #include "glheader.h"
@@ -49,7 +49,7 @@
  *
  * Updates gl_stencil_attrib::Clear. On change
  * flushes the vertices and notifies the driver via
- * dd_function_table::ClearStencil.
+ * the dd_function_table::ClearStencil callback.
  */
 void
 _mesa_ClearStencil( GLint s )
@@ -80,7 +80,7 @@ _mesa_ClearStencil( GLint s )
  *
  * Verifies the parameters and updates the respective values in
  * __GLcontextRec::Stencil. On change flushes the vertices and notifies the
- * driver via dd_function_table::StencilFunc.
+ * driver via the dd_function_table::StencilFunc callback.
  */
 void
 _mesa_StencilFunc( GLenum func, GLint ref, GLuint mask )
@@ -133,7 +133,7 @@ _mesa_StencilFunc( GLenum func, GLint ref, GLuint mask )
  * \sa glStencilMask().
  *
  * Updates gl_stencil_attrib::WriteMask. On change flushes the vertices and
- * notifies the driver via dd_function_table::StencilMask.
+ * notifies the driver via the dd_function_table::StencilMask callback.
  */
 void
 _mesa_StencilMask( GLuint mask )
@@ -166,7 +166,7 @@ _mesa_StencilMask( GLuint mask )
  * 
  * Verifies the parameters and updates the respective fields in
  * __GLcontextRec::Stencil. On change flushes the vertices and notifies the
- * driver via dd_function_table::StencilOp.
+ * driver via the dd_function_table::StencilOp callback.
  */
 void
 _mesa_StencilOp(GLenum fail, GLenum zfail, GLenum zpass)
@@ -271,7 +271,7 @@ _mesa_ActiveStencilFaceEXT(GLenum face)
  *
  * \param ctx GL context.
  *
- * Initializes __GLcontextRec::Stipple attribute group.
+ * Initializes __GLcontextRec::Stencil attribute group.
  */
 void _mesa_init_stencil( GLcontext * ctx )
 {
diff --git a/src/mesa/main/texobj.c b/src/mesa/main/texobj.c
index c85a87cb936..3db47d507f9 100644
--- a/src/mesa/main/texobj.c
+++ b/src/mesa/main/texobj.c
@@ -27,7 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: texobj.c,v 1.62.4.6 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: texobj.c,v 1.62.4.7 2003/03/23 23:22:48 jrfonseca Exp $ */
 
 #include "glheader.h"
 #include "colortab.h"
@@ -604,9 +604,9 @@ _mesa_GenTextures( GLsizei n, GLuint *texName )
  *
  * \sa glDeleteTextures().
  *
- * For each texture checks if its bound to any of the texture units, unbind it
- * and decrementing the reference count if so. If the texture reference count
- * is zero, delete its object.
+ * For each texture checks if its bound to any of the texture units, unbinding
+ * it and decrementing the reference count if so. If the texture reference
+ * count is zero, delete its object.
  */
 void
 _mesa_DeleteTextures( GLsizei n, const GLuint *texName)
diff --git a/src/mesa/main/varray.h b/src/mesa/main/varray.h
index 471a06c6365..854f5cf44e3 100644
--- a/src/mesa/main/varray.h
+++ b/src/mesa/main/varray.h
@@ -3,7 +3,7 @@
  * \brief Vertex arrays.
  *
  * \if subset
- * \brief (No-op.)
+ * \brief (No-op)
  *
  * \endif
  */
@@ -32,7 +32,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: varray.h,v 1.14.6.2 2003/03/23 03:51:34 jrfonseca Exp $ */
+/* $Id: varray.h,v 1.14.6.3 2003/03/23 23:22:48 jrfonseca Exp $ */
 
 
 #ifndef VARRAY_H
diff --git a/src/mesa/math/m_matrix.c b/src/mesa/math/m_matrix.c
index a562c6065ea..35a1482e24e 100644
--- a/src/mesa/math/m_matrix.c
+++ b/src/mesa/math/m_matrix.c
@@ -32,7 +32,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: m_matrix.c,v 1.14.4.3 2003/03/23 14:58:08 jrfonseca Exp $ */
+/* $Id: m_matrix.c,v 1.14.4.4 2003/03/23 23:22:49 jrfonseca Exp $ */
 
 
 #include "glheader.h"
@@ -139,7 +139,7 @@ static void matmul34( GLfloat *product, const GLfloat *a, const GLfloat *b )
  * \param m right multiplication matrix array.
  * \param flags flags of the matrix \p m.
  * 
- * Joins both flags and marks the type and inverse as drity.  Calls matmul34()
+ * Joins both flags and marks the type and inverse as dirty.  Calls matmul34()
  * if both matrices are 3D, or matmul4() otherwise.
  */
 static void matrix_multf( GLmatrix *mat, const GLfloat *m, GLuint flags )
@@ -155,6 +155,12 @@ static void matrix_multf( GLmatrix *mat, const GLfloat *m, GLuint flags )
 /**
  * \brief Matrix multiplication.
  *
+ * \param dest destination matrix.
+ * \param a left matrix.
+ * \param b right matrix.
+ * 
+ * Joins both flags and marks the type and inverse as dirty.  Calls matmul34()
+ * if both matrices are 3D, or matmul4() otherwise.
  */
 void
 _math_matrix_mul_matrix( GLmatrix *dest, const GLmatrix *a, const GLmatrix *b )
@@ -170,7 +176,15 @@ _math_matrix_mul_matrix( GLmatrix *dest, const GLmatrix *a, const GLmatrix *b )
       matmul4( dest->m, a->m, b->m );
 }
 
-
+/**
+ * \brief Matrix multiplication.
+ *
+ * \param dest left and destination matrix.
+ * \param m right matrix array.
+ * 
+ * Marks the matrix flags with general flag, and type and inverse dirty flags.
+ * Calls matmul4() for the multiplication.
+ */
 void
 _math_matrix_mul_floats( GLmatrix *dest, const GLfloat *m )
 {
@@ -1253,7 +1267,7 @@ static void analyse_from_flags( GLmatrix *mat )
  * If the matrix type is dirty then calls either analyse_from_scratch() or
  * analyse_from_flags() to determine its type, according to whether the flags
  * are dirty or not, respectively. If the matrix has an inverse and it's dirty
- * then calls matrix inverse. Finally clears the firty flags.
+ * then calls matrix_invert(). Finally clears the firty flags.
  */
 void
 _math_matrix_analyse( GLmatrix *mat )