documentation updates

9 files changed, 140 insertions, 19 deletions

diff --git a/src/mesa/array_cache/acache.h b/src/mesa/array_cache/acache.h
index d6935235db9..85aa3137f1f 100644
--- a/src/mesa/array_cache/acache.h
+++ b/src/mesa/array_cache/acache.h
@@ -1,8 +1,8 @@
-/* $Id: acache.h,v 1.4 2002/10/29 20:28:58 brianp Exp $ */
+/* $Id: acache.h,v 1.4.4.1 2003/01/10 21:57:42 brianp Exp $ */
 
 /*
  * Mesa 3-D graphics library
- * Version:  4.1
+ * Version:  5.0
  *
  * Copyright (C) 1999-2002  Brian Paul   All Rights Reserved.
  *
@@ -23,10 +23,23 @@
  * 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>
  */
 
+
+/**
+ * \mainpage Mesa array_cache Module
+ *
+ * The array cache module is used for caching vertex arrays.
+ */
+
+
+/**
+ * \file array_cache/acache.h
+ * \brief Array cache functions (for vertex arrays).
+ * \author Keith Whitwell
+ */
+
+
 #ifndef _ARRAYCACHE_H
 #define _ARRAYCACHE_H
 
diff --git a/src/mesa/drivers/common/t_dd_vertex.h b/src/mesa/drivers/common/t_dd_vertex.h
index acd35aafadf..8b8a1f922a0 100644
--- a/src/mesa/drivers/common/t_dd_vertex.h
+++ b/src/mesa/drivers/common/t_dd_vertex.h
@@ -1,4 +1,4 @@
-/* $Id: t_dd_vertex.h,v 1.13 2002/10/29 20:29:05 brianp Exp $ */
+/* $Id: t_dd_vertex.h,v 1.13.4.1 2003/01/10 21:57:43 brianp Exp $ */
 
 /*
  * Mesa 3-D graphics library
@@ -27,6 +27,16 @@
  *    Keith Whitwell <keith@tungstengraphics.com>
  */
 
+
+
+/**
+ * \mainpage Mesa TNL Device Driver Module
+ *
+ * This module contains functions useful for hardware device drivers.
+ * For example, building D3D-style vertex buffers.
+ */
+
+
 typedef struct {
    GLfloat x, y, z, w;
 } TAG(_coord_t);
diff --git a/src/mesa/main/context.c b/src/mesa/main/context.c
index e9334517200..60fe4c30bbb 100644
--- a/src/mesa/main/context.c
+++ b/src/mesa/main/context.c
@@ -1,4 +1,4 @@
-/* $Id: context.c,v 1.188.2.1.2.1 2002/12/12 14:22:02 keithw Exp $ */
+/* $Id: context.c,v 1.188.2.1.2.2 2003/01/10 21:57:41 brianp Exp $ */
 
 /*
  * Mesa 3-D graphics library
@@ -25,6 +25,56 @@
  */
 
 
+
+/**
+ * \mainpage Mesa Core Module
+ *
+ * \section CoreIntroduction Introduction
+ *
+ * The Mesa core module consists of all the top-level files in the src
+ * directory.  The core module basically takes care of API dispatch,
+ * and OpenGL state management.
+ *
+ * For example, calls to glPolygonMode are routed to _mesa_PolygonMode()
+ * which updates the state related to polygonmode.  Furthermore, dirty
+ * state flags related to polygon mode are set and if the device driver
+ * implements a special routine for PolygonMode, it will be called.
+ *
+ *
+ * \section AboutDoxygen About Doxygen
+ *
+ * If you're viewing this information as Doxygen-generated HTML you'll
+ * see the documentation index at the top of this page.
+ *
+ * The first line lists the Mesa source code modules.
+ * The second line lists the indexes available for viewing the documentation
+ * for each module.
+ *
+ * Selecting the <b>Main page</b> link will display a summary of the module
+ * (this page).
+ *
+ * Selecting <b>Compound List</b> will list all C structures.
+ *
+ * Selecting the <b>File List</b> link will list all the source files in
+ * the module.
+ * Selecting a filename will show a list of all functions defined in that file.
+ *
+ * Selecting the <b>Compound Members</b> link will display a list of all
+ * documented structure members.
+ *
+ * Selecting the <b>File Members</b> link will display a list
+ * of all functions, structures, global variables and macros in the module.
+ *
+ */
+
+
+/**
+ * \file context.c
+ * \brief Mesa context/visual/framebuffer management functions.
+ * \author Brian Paul
+ */
+
+
 #include "glheader.h"
 #include "imports.h"
 #include "buffers.h"
@@ -1872,7 +1922,7 @@ _mesa_initialize_context( GLcontext *ctx,
 
 
 
-/*
+/**
  * Allocate and initialize a GLcontext structure.
  * Input:  visual - a GLvisual pointer (we copy the struct contents)
  *         sharelist - another context to share display lists with or NULL
@@ -1907,7 +1957,7 @@ _mesa_create_context( const GLvisual *visual,
 
 
 
-/*
+/**
  * Free the data associated with the given context.
  * But don't free() the GLcontext struct itself!
  */
@@ -2025,7 +2075,7 @@ _mesa_free_context_data( GLcontext *ctx )
 
 
 
-/*
+/**
  * Destroy a GLcontext structure.
  */
 void
diff --git a/src/mesa/main/polygon.c b/src/mesa/main/polygon.c
index a347b615df1..cb2f1e03395 100644
--- a/src/mesa/main/polygon.c
+++ b/src/mesa/main/polygon.c
@@ -1,4 +1,4 @@
-/* $Id: polygon.c,v 1.25 2002/10/24 23:57:21 brianp Exp $ */
+/* $Id: polygon.c,v 1.25.4.1 2003/01/10 21:57:41 brianp Exp $ */
 
 /*
  * Mesa 3-D graphics library
@@ -89,6 +89,9 @@ _mesa_FrontFace( GLenum mode )
 
 
 
+/**
+ * Execute glPolygonMode (error checking, update state, set dirty flags).
+ */
 void
 _mesa_PolygonMode( GLenum face, GLenum mode )
 {
diff --git a/src/mesa/math/mathmod.h b/src/mesa/math/mathmod.h
index 44bf2b97d5b..f6d3553e992 100644
--- a/src/mesa/math/mathmod.h
+++ b/src/mesa/math/mathmod.h
@@ -1,4 +1,4 @@
-/* $Id: mathmod.h,v 1.3 2001/03/12 00:48:41 gareth Exp $ */
+/* $Id: mathmod.h,v 1.3.8.1 2003/01/10 21:57:42 brianp Exp $ */
 
 /*
  * Mesa 3-D graphics library
@@ -24,6 +24,16 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
+/**
+ * \mainpage Mesa Math Module
+ *
+ * This module contains math-related utility functions for transforming
+ * vertices, translating arrays of numbers from one datatype to another,
+ * evaluating curved surfaces, etc.
+ */
+
+
 #ifndef _MESA_MATH_H_
 #define _MESA_MATH_H_
 
diff --git a/src/mesa/swrast/s_context.h b/src/mesa/swrast/s_context.h
index e1c22977dd8..5b4d66515b6 100644
--- a/src/mesa/swrast/s_context.h
+++ b/src/mesa/swrast/s_context.h
@@ -1,4 +1,4 @@
-/* $Id: s_context.h,v 1.22 2002/10/29 20:29:00 brianp Exp $ */
+/* $Id: s_context.h,v 1.22.4.1 2003/01/10 21:57:42 brianp Exp $ */
 
 /*
  * Mesa 3-D graphics library
@@ -70,7 +70,7 @@ typedef void (*swrast_tri_func)( GLcontext *ctx, const SWvertex *,
                                  const SWvertex *, const SWvertex *);
 
 
-/** \defgroup Bitmasks
+/** \defgroup rasterBits RasterMask Bits
  * Bitmasks to indicate which rasterization options are enabled
  * (RasterMask)
  */
diff --git a/src/mesa/swrast/swrast.h b/src/mesa/swrast/swrast.h
index 83856214097..b39b7294f98 100644
--- a/src/mesa/swrast/swrast.h
+++ b/src/mesa/swrast/swrast.h
@@ -1,4 +1,4 @@
-/* $Id: swrast.h,v 1.32.4.1 2002/12/30 15:20:37 keithw Exp $ */
+/* $Id: swrast.h,v 1.32.4.2 2003/01/10 21:57:42 brianp Exp $ */
 
 /*
  * Mesa 3-D graphics library
@@ -26,6 +26,19 @@
  */
 
 /**
+ * \mainpage Mesa Software Rasterization (swrast) Module
+ *
+ * This module is responsible for the following:
+ *   - rendering points (wide, smoothed, textured, etc)
+ *   - rendering lines (wide, stippled, smoothed, etc)
+ *   - renering triangles (stippled, smoothed, textured, etc)
+ *
+ * Hardware drivers won't typically use these facilities, except for
+ * fallback cases such as when the hardware can't do antialiasing.
+ */
+
+
+/**
  * \file swrast/swrast.h
  * \brief Defines basic structures for sw_rasterizer.
  * \author Keith Whitwell <keith@tungstengraphics.com>
diff --git a/src/mesa/swrast_setup/swrast_setup.h b/src/mesa/swrast_setup/swrast_setup.h
index acf8fa5d220..da5b64ba1e4 100644
--- a/src/mesa/swrast_setup/swrast_setup.h
+++ b/src/mesa/swrast_setup/swrast_setup.h
@@ -1,4 +1,4 @@
-/* $Id: swrast_setup.h,v 1.10 2002/10/29 20:29:01 brianp Exp $ */
+/* $Id: swrast_setup.h,v 1.10.4.1 2003/01/10 21:57:43 brianp Exp $ */
 
 /*
  * Mesa 3-D graphics library
@@ -27,7 +27,14 @@
  *    Keith Whitwell <keith@tungstengraphics.com>
  */
 
-/* Public interface to the swrast_setup module.  This module provides
+
+/**
+ * \mainpage Mesa Software Rasterization Setup (swrast_setup) Module
+ *
+ * This module lies between the tnl and swrast stages.  It basically converts
+ * vertex buffers into vertices suitable for use by swrast.
+ *
+ * Public interface to the swrast_setup module.  This module provides
  * an implementation of the driver interface to t_vb_render.c, and uses
  * the software rasterizer (swrast) to perform actual rasterization.
  *
diff --git a/src/mesa/tnl/tnl.h b/src/mesa/tnl/tnl.h
index db0f7b59bb5..d5f465ea548 100644
--- a/src/mesa/tnl/tnl.h
+++ b/src/mesa/tnl/tnl.h
@@ -1,10 +1,10 @@
-/* $Id: tnl.h,v 1.10.4.1 2002/12/30 15:20:38 keithw Exp $ */
+/* $Id: tnl.h,v 1.10.4.2 2003/01/10 21:57:43 brianp Exp $ */
 
 /*
  * Mesa 3-D graphics library
- * Version:  3.5
+ * Version:  5.0.1
  *
- * Copyright (C) 1999-2001  Brian Paul   All Rights Reserved.
+ * Copyright (C) 1999-2003  Brian Paul   All Rights Reserved.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -27,6 +27,21 @@
  *    Keith Whitwell <keith@tungstengraphics.com>
  */
 
+
+/**
+ * \mainpage Mesa Transform and Lighting (TnL) Module
+ *
+ * This module is responsible for the following:
+ *   - building vertex buffers from glVertex, glColor, etc calls
+ *   - transforming vertices by the modelview and projection matrices
+ *   - view volume and user-defined clipping
+ *   - lighting
+ *   - texgen
+ *   - fog
+ *   - vertex program execution
+ */
+
+
 #ifndef _TNL_H
 #define _TNL_H