Last bits of documentation. Full review still pending.

8 files changed, 221 insertions, 136 deletions

diff --git a/src/mesa/drivers/dri/radeon/radeon_context.c b/src/mesa/drivers/dri/radeon/radeon_context.c
index 43df0a0b62..fd9ab8a33f 100644
--- a/src/mesa/drivers/dri/radeon/radeon_context.c
+++ b/src/mesa/drivers/dri/radeon/radeon_context.c
@@ -497,10 +497,12 @@ radeonCreateContext( const __GLcontextModes *glVisual,
  *
  * \param driContextPriv DRI specific context data.
  *
- * If destroying the currently bound context, fires the vertices and unbinds it first.
+ * If destroying the currently bound context, fires the vertices and unbinds it
+ * first.
  *
- * Frees the radeon context resources, freeing the Mesa context. Frees the private texture object from
- * the shared context data if its reference count reaches zero.
+ * Frees the radeon context resources, freeing the Mesa context. Frees the
+ * private texture object from the shared context data if its reference count
+ * reaches zero.
  */
 static void
 radeonDestroyContext( __DRIcontextPrivate *driContextPriv )
@@ -576,8 +578,6 @@ radeonDestroyContext( __DRIcontextPrivate *driContextPriv )
 }
 
 
-
-
 /**
  * \brief Create and initialize the Mesa and device specific pixmap buffer
  * data.
@@ -586,6 +586,8 @@ radeonDestroyContext( __DRIcontextPrivate *driContextPriv )
  * \param driDrawPriv DRI specific drawable data.
  * \param mesaVis visual.
  * \param isPixmap must be GL_FALSE. Not implemented.
+ *
+ * Calls _mesa_create_framebuffer() to create the framebuffer.
  */
 static GLboolean
 radeonCreateBuffer( __DRIscreenPrivate *driScrnPriv,
@@ -625,7 +627,7 @@ radeonCreateBuffer( __DRIscreenPrivate *driScrnPriv,
  *
  * \param driDrawPriv DRI specific drawable data.
  *
- * Destroys Mesa framebuffer.
+ * Calls _mesa_destroy_framebuffer() to destroy Mesa framebuffer.
  */
 static void
 radeonDestroyBuffer(__DRIdrawablePrivate *driDrawPriv)
@@ -673,12 +675,15 @@ radeonSwapBuffers( __DRIdrawablePrivate *dPriv )
  * \brief Set the current context.
  * 
  * \param driContextPriv DRI specific context data to be activated. 
- * \param driDrawPriv DRI specific drawable data, to which the context is to be associated for writing.
- * \param driReadPriv DRI specific drawable data, to which the context is to be associated for reading.
+ * \param driDrawPriv DRI specific drawable data, to which the context is to be
+ * associated for writing.
+ * \param driReadPriv DRI specific drawable data, to which the context is to be
+ * associated for reading.
  *
  * \return GL_TRUE on success, or GL_FALSE on failure.
  *
- * 
+ * If drawables differ form the current ones then update the window and
+ * viewport information.  Calls _mesa_make_current2() to set the context.
  */
 static GLboolean
 radeonMakeCurrent( __DRIcontextPrivate *driContextPriv,
@@ -727,6 +732,10 @@ radeonMakeCurrent( __DRIcontextPrivate *driContextPriv,
 /**
  * \brief Unbind context from its buffer.
  *
+ * \param driContextPriv DRI specifc context data.
+ *
+ * \returns always GL_TRUE.
+ *
  * Calls radeonVtxfmtUnbindContext().
  */
 static GLboolean
diff --git a/src/mesa/drivers/dri/radeon/radeon_ioctl.c b/src/mesa/drivers/dri/radeon/radeon_ioctl.c
index ca1c265df5..40c6e2ad8b 100644
--- a/src/mesa/drivers/dri/radeon/radeon_ioctl.c
+++ b/src/mesa/drivers/dri/radeon/radeon_ioctl.c
@@ -502,6 +502,16 @@ void radeonRefillCurrentDmaRegion( radeonContextPtr rmesa )
    rmesa->dma.current.ptr = 0;
 }
 
+/**
+ * \brief Release DMA region.
+ *
+ * \param rmesa Radeon context.
+ * \param region ragion to be released.
+ * \param caller caller's name for debugging purposes.
+ *
+ * Decreases the region reference count, and if it reaches zero sends the
+ * RADEON_CMD_DMA_DISCARD with its buffer index.
+ */
 void radeonReleaseDmaRegion( radeonContextPtr rmesa,
 			     struct radeon_dma_region *region,
 			     const char *caller )
@@ -538,11 +548,12 @@ void radeonReleaseDmaRegion( radeonContextPtr rmesa,
  * \brief Allocates a new region from rmesa->dma.current.
  *
  * \param rmesa Radeon context.
- * \param region will received the allocated region.
- * \param bytes size
- * \param alignment
+ * \param region region will received the allocated region.
+ * \param bytes size.
+ * \param alignment alignment.
  * 
- * If there isn't enough space incurrent, grab a new buffer (and discard what was left of current).
+ * If there isn't enough space in current, grab a new buffer (and discard what
+ * was left of current).
  */
 void radeonAllocDmaRegion( radeonContextPtr rmesa, 
 			   struct radeon_dma_region *region,
@@ -886,9 +897,9 @@ void radeonPageFlip( const __DRIdrawablePrivate *dPriv )
  * \param ch clearing rectangle height.
  *
  * First emits the current state, fires the vertices and calculate the clearing
- * flags to pass to the clear IOCTL later.
+ * flags to pass to the clear ioctl later.
  *
- * Locks the hardware and throttles the number of clear IOCTLS done, allowing
+ * Locks the hardware and throttles the number of clear ioctl's done, allowing
  * up to #RADEON_MAX_CLEARS. For each set of cliprects, intersects them with
  * the clearing rectangle (if not clearing all) and uploads them to the SAREA,
  * setups a drmRadeonClearType structure sends it to the DRM_RADEON_CLEAR
diff --git a/src/mesa/drivers/dri/radeon/radeon_subset_tex.c b/src/mesa/drivers/dri/radeon/radeon_subset_tex.c
index 686e391eec..cf22dbe68e 100644
--- a/src/mesa/drivers/dri/radeon/radeon_subset_tex.c
+++ b/src/mesa/drivers/dri/radeon/radeon_subset_tex.c
@@ -141,7 +141,7 @@ void radeonAgeTextures( radeonContextPtr rmesa, int heap )
  * \param height sub-imate height.
  *
  * Fills in a drmRadeonTexture and drmRadeonTexImage structures and uploads the
- * texture via the DRM_RADEON_TEXTURE IOCTL, aborting in case of failure.
+ * texture via the DRM_RADEON_TEXTURE ioctl, aborting in case of failure.
  */
 static void radeonUploadSubImage( radeonContextPtr rmesa,
 				  radeonTexObjPtr t, GLint level,
diff --git a/src/mesa/drivers/dri/radeon/server/radeon.h b/src/mesa/drivers/dri/radeon/server/radeon.h
index 1865083a15..c2430bd054 100644
--- a/src/mesa/drivers/dri/radeon/server/radeon.h
+++ b/src/mesa/drivers/dri/radeon/server/radeon.h
@@ -64,6 +64,9 @@
 #define PCI_CHIP_R200_Ql		0x516C
 
 
+/**
+ * \brief Chip families.
+ */
 typedef enum {
     CHIP_FAMILY_UNKNOW,
     CHIP_FAMILY_LEGACY,
@@ -80,39 +83,45 @@ typedef enum {
     CHIP_FAMILY_R300
 } RADEONChipFamily;
 
+
 typedef unsigned long memType;
 
 
 /**
- * \brief Radeon driver private data.
+ * \brief Radeon DDX driver private data.
  */
 typedef struct {
-   int               Chipset;
-   RADEONChipFamily  ChipFamily;
+   int               Chipset;          /**< \brief Chipset number */
+   RADEONChipFamily  ChipFamily;       /**< \brief Chip family */
 
    unsigned long     LinearAddr;       /**< \brief Frame buffer physical address */
 
 
-   drmSize           registerSize;
-   drmHandle         registerHandle;
+   drmSize           registerSize;     /**< \brief MMIO register map size */
+   drmHandle         registerHandle;   /**< \brief MMIO register map handle */
 
-   drmSize           agpSize;
-   drmHandle         agpMemHandle;     /**< \brief Handle from drmAgpAlloc */
-   unsigned long     agpOffset;
-   int               agpMode;
+   /**
+    * \name AGP
+    */
+   /*@{*/
+   drmSize           agpSize;          /**< \brief AGP map size */
+   drmHandle         agpMemHandle;     /**< \brief AGP map handle */
+   unsigned long     agpOffset;        /**< \brief AGP offset */
+   int               agpMode;          /**< \brief AGP mode */
    int               agpFastWrite;
+   /*@}*/
 
    /**
     * \name CP ring buffer data
     */
    /*@{*/
    unsigned long     ringStart;        /**< \brief Offset into AGP space */
-   drmHandle         ringHandle;       /**< \brief Handle from drmAddMap */
+   drmHandle         ringHandle;       /**< \brief Handle from drmAddMap() */
    drmSize           ringMapSize;      /**< \brief Size of map */
    int               ringSize;         /**< \brief Size of ring (in MB) */
 
-   unsigned long     ringReadOffset;   /**< \brief Offset into AGP space */
-   drmHandle         ringReadPtrHandle;/**< \brief Handle from drmAddMap */
+   unsigned long     ringReadOffset;   /**< \brief Read offset into AGP space */
+   drmHandle         ringReadPtrHandle;/**< \brief Handle from drmAddMap() */
    drmSize           ringReadMapSize;  /**< \brief Size of map */
    /*@}*/
 
@@ -121,7 +130,7 @@ typedef struct {
     */
    /*@{*/
    unsigned long     bufStart;         /**< \brief Offset into AGP space */
-   drmHandle         bufHandle;        /**< \brief Handle from drmAddMap */
+   drmHandle         bufHandle;        /**< \brief Handle from drmAddMap() */
    drmSize           bufMapSize;       /**< \brief Size of map */
    int               bufSize;          /**< \brief Size of buffers (in MB) */
    int               bufNumBufs;       /**< \brief Number of buffers */
@@ -132,29 +141,29 @@ typedef struct {
     */
    /*@{*/
    unsigned long     agpTexStart;      /**< \brief Offset into AGP space */
-   drmHandle         agpTexHandle;     /**< \brief Handle from drmAddMap */
+   drmHandle         agpTexHandle;     /**< \brief Handle from drmAddMap() */
    drmSize           agpTexMapSize;    /**< \brief Size of map */
    int               agpTexSize;       /**< \brief Size of AGP tex space (in MB) */
    int               log2AGPTexGran;
    /*@}*/
 
-   int               drmMinor;
+   int               drmMinor;         /**< \brief DRM device minor number */
 
-   int               frontOffset;
-   int               frontPitch;
-   int               backOffset;
-   int               backPitch;
-   int               depthOffset;
-   int               depthPitch;
-   int               textureOffset;
-   int               textureSize;
-   int               log2TexGran;
+   int               frontOffset;      /**< \brief Front color buffer offset */
+   int               frontPitch;       /**< \brief Front color buffer pitch */
+   int               backOffset;       /**< \brief Back color buffer offset */
+   int               backPitch;        /**< \brief Back color buffer pitch */
+   int               depthOffset;      /**< \brief Depth buffer offset */
+   int               depthPitch;       /**< \brief Depth buffer pitch */
+   int               textureOffset;    /**< \brief Texture area offset */
+   int               textureSize;      /**< \brief Texture area size */
+   int               log2TexGran;      /**< \brief Texture granularity in base 2 log */
 
    unsigned int      frontPitchOffset;
    unsigned int      backPitchOffset;
-   unsigned int      depthPitchOffset;
+   unsigned int      depthPitchOffset
 
-   int               irq;
+   int               irq;              /**< \brief IRQ number */
    unsigned int      gen_int_cntl;
    unsigned int      crtc_offset_cntl;
 
diff --git a/src/mesa/drivers/dri/radeon/server/radeon_common.h b/src/mesa/drivers/dri/radeon/server/radeon_common.h
index eab71f2e33..2a8425df89 100644
--- a/src/mesa/drivers/dri/radeon/server/radeon_common.h
+++ b/src/mesa/drivers/dri/radeon/server/radeon_common.h
@@ -87,33 +87,43 @@
 #define RADEON_CLEAR_DEPTH     4
 
 
+/**
+ * \brief DRM_RADEON_CP_INIT ioctl argument type.
+ */
 typedef struct {
+   /** \brief request */
    enum {
-      DRM_RADEON_INIT_CP    = 0x01,
-      DRM_RADEON_CLEANUP_CP = 0x02,
-      DRM_RADEON_INIT_R200_CP = 0x03
+      DRM_RADEON_INIT_CP    = 0x01,  /**< \brief initialize CP */
+      DRM_RADEON_CLEANUP_CP = 0x02,  /**< \brief clean up CP */
+      DRM_RADEON_INIT_R200_CP = 0x03 /**< \brief initialize R200 CP */
    } func;
-   unsigned long sarea_priv_offset;
-   int is_pci;
-   int cp_mode;
-   int agp_size;
-   int ring_size;
-   int usec_timeout;
-
-   unsigned int fb_bpp;
-   unsigned int front_offset, front_pitch;
-   unsigned int back_offset, back_pitch;
-   unsigned int depth_bpp;
-   unsigned int depth_offset, depth_pitch;
-
-   unsigned long fb_offset;
-   unsigned long mmio_offset;
-   unsigned long ring_offset;
-   unsigned long ring_rptr_offset;
-   unsigned long buffers_offset;
-   unsigned long agp_textures_offset;
+   unsigned long sarea_priv_offset;   /**< \brief SAREA private offset */
+   int is_pci;                        /**< \brief is current card a PCI card? */
+   int cp_mode;                       /**< \brief CP mode */
+   int agp_size;                      /**< \brief AGP space size */
+   int ring_size;                     /**< \brief CP ring buffer size */
+   int usec_timeout;                  /**< \brief timeout for DRM operations in usecs */
+
+   unsigned int fb_bpp;               
+   unsigned int front_offset;         /**< \brief front color buffer offset */
+   unsigned int front_pitch;          /**< \brief front color buffer pitch */
+   unsigned int back_offset;          /**< \brief back color buffer offset */
+   unsigned int back_pitch;           /**< \brief back color buffer pitch*/
+   unsigned int depth_bpp;            /**< \brief depth buffer bits-per-pixel */
+   unsigned int depth_offset;         /**< \brief depth buffer offset */
+   unsigned int depth_pitch;          /**< \brief depth buffer pitch */
+
+   unsigned long fb_offset;           /**< \brief framebuffer offset */
+   unsigned long mmio_offset;         /**< \brief MMIO register offset */
+   unsigned long ring_offset;         /**< \brief CP ring buffer offset */
+   unsigned long ring_rptr_offset;    /**< \brief CP ring buffer read pointer offset */
+   unsigned long buffers_offset;      /**< \brief vertex buffers offset */
+   unsigned long agp_textures_offset; /**< \brief AGP textures offset */
 } drmRadeonInit;
 
+/**
+ * \brief DRM_RADEON_CP_STOP ioctl argument type.
+ */
 typedef struct {
    int flush;
    int idle;
@@ -131,6 +141,9 @@ typedef union drmRadeonClearR {
         unsigned int ui[5];
 } drmRadeonClearRect;
 
+/**
+ * \brief DRM_RADEON_CLEAR ioctl argument type.
+ */
 typedef struct drmRadeonClearT {
         unsigned int flags;
         unsigned int clear_color;
@@ -147,6 +160,9 @@ typedef struct drmRadeonFullscreenT {
         } func;
 } drmRadeonFullscreenType;
 
+/**
+ * \brief DRM_RADEON_STIPPLE ioctl argument type.
+ */
 typedef struct {
         unsigned int *mask;
 } drmRadeonStipple;
@@ -159,18 +175,22 @@ typedef struct {
         const void *data;
 } drmRadeonTexImage;
 
+/**
+ * \brief DRM_RADEON_TEXTURE ioctl argument type.
+ */
 typedef struct {
-        int offset;
-        int pitch;
-        int format;
-        int width;                      /* Texture image coordinates */
-        int height;
-        drmRadeonTexImage *image;
+        int offset;               /**< \brief texture offset */
+        int pitch;                /**< \brief texture pitch */
+        int format;               /**< \brief pixel format */
+        int width;                /**< \brief texture width */
+        int height;               /**< \brief texture height */
+	drmRadeonTexImage *image; /**< \brief image */
 } drmRadeonTexture;
 
 
 #define RADEON_MAX_TEXTURE_UNITS 3
 
+
 /* Layout matches drm_radeon_state_t in linux drm_radeon.h.  
  */
 typedef struct {
@@ -240,13 +260,16 @@ typedef struct {
 	unsigned int dirty;
 } drmRadeonState;
 
-/* 1.1 vertex ioctl.  Used in compatibility modes.
+/**
+ * \brief DRM 1.1 vertex ioctl.
+ *
+ * Used in compatibility modes.
  */
 typedef struct {
-	int prim;
-	int idx;			/* Index of vertex buffer */
-	int count;			/* Number of vertices in buffer */
-	int discard;			/* Client finished with buffer? */
+	int prim;			/**< \brief Primitive number */
+	int idx;			/**< \brief Index of vertex buffer */
+	int count;			/**< \brief Number of vertices in buffer */
+	int discard;			/**< \brief Client finished with buffer? */
 } drmRadeonVertex;
 
 typedef struct {
@@ -254,13 +277,13 @@ typedef struct {
 	unsigned int finish;
 	unsigned int prim:8;
 	unsigned int stateidx:8;
-	unsigned int numverts:16; /* overloaded as offset/64 for elt prims */
+	unsigned int numverts:16;	/**< overloaded as offset/64 for elt prims */
         unsigned int vc_format;
 } drmRadeonPrim;
 
 typedef struct {
-        int idx;                        /* Index of vertex buffer */
-        int discard;                    /* Client finished with buffer? */
+        int idx;                        /**< \brief Index of vertex buffer */
+        int discard;                    /**< \brief Client finished with buffer? */
         int nr_states;
         drmRadeonState *state;
         int nr_prims;
@@ -270,22 +293,27 @@ typedef struct {
 #define RADEON_MAX_STATES 16
 #define RADEON_MAX_PRIMS  64
 
-/* Command buffer.  Replace with true dma stream?
+
+/**
+ * \brief Command buffer.  
+ *
+ * \todo Replace with true dma stream?
  */
 typedef struct {
-	int bufsz;
-	char *buf;
-	int nbox;
-        drmClipRect *boxes;
+	int bufsz;          /**< \brief buffer size */
+	char *buf;          /**< \brief buffer */
+	int nbox;           /**< \brief number of cliprects */
+        drmClipRect *boxes; /**< \brief cliprects */
 } drmRadeonCmdBuffer;
 
+
 /**
- * \brief New style per-packet identifiers for use in cmd_buffer IOCTL with
- * the RADEON_EMIT_PACKET command.  
+ * \brief Per-packet identifiers for use with the ::RADEON_CMD_PACKET command
+ * in the DRM_RADEON_CMDBUF ioctl.  
  *
  * \note Comments relate new packets to old state bits and the packet size.
  */
-enum {
+enum drmRadeonCmdPkt {
    RADEON_EMIT_PP_MISC                       = 0, /* context/7 */
    RADEON_EMIT_PP_CNTL                       = 1, /* context/3 */
    RADEON_EMIT_RB3D_COLORPITCH               = 2, /* context/1 */
@@ -364,25 +392,25 @@ enum {
 
 
 /**
- * \brief Command types understood by cmd_buffer IOCTL.  
+ * \brief Command types understood by the DRM_RADEON_CMDBUF ioctl.  
  * 
  * More can be added but obviously these can't be removed or changed.
  *
  * \sa drmRadeonCmdHeader.
  */
 enum drmRadeonCmdType {
-   RADEON_CMD_PACKET       = 1, /**< \brief emit one of the register packets above */
+   RADEON_CMD_PACKET       = 1, /**< \brief emit one of the ::drmRadeonCmdPkt register packets */
    RADEON_CMD_SCALARS      = 2, /**< \brief emit scalar data */
    RADEON_CMD_VECTORS      = 3, /**< \brief emit vector data */
    RADEON_CMD_DMA_DISCARD  = 4, /**< \brief discard current DMA buffer */
-   RADEON_CMD_PACKET3      = 5, /**< \brief emit hw packet */
-   RADEON_CMD_PACKET3_CLIP = 6, /**< \brief emit hw packet wrapped in cliprects */
+   RADEON_CMD_PACKET3      = 5, /**< \brief emit hardware packet */
+   RADEON_CMD_PACKET3_CLIP = 6, /**< \brief emit hardware packet wrapped in cliprects */
    RADEON_CMD_SCALARS2     = 7, /**< \brief R200 stopgap */
    RADEON_CMD_WAIT         = 8  /**< \brief synchronization */
 } ;
 
 /**
- * \brief Commands understood by cmd_buffer IOCTL.
+ * \brief Commands understood by the DRM_RADEON_CMDBUF ioctl.
  *
  * \sa drmRadeonCmdType.
  */
@@ -424,10 +452,12 @@ typedef union {
 #define RADEON_WAIT_2D  0x1
 #define RADEON_WAIT_3D  0x2
 
-
+/**
+ * \brief DRM_RADEON_GETPARAM ioctl argument type.
+ */
 typedef struct drm_radeon_getparam {
-	int param;
-	int *value;
+	int param;  /**< \brief parameter number */
+	int *value; /**< \brief parameter value */
 } drmRadeonGetParam;
 
 #define RADEON_PARAM_AGP_BUFFER_OFFSET 1
@@ -459,12 +489,20 @@ typedef struct drm_radeon_mem_init_heap {
 	int start;	
 } drmRadeonMemInitHeap;
 
-/* 1.6: Userspace can request & wait on irq's:
+/**
+ * \brief DRM_RADEON_IRQ_EMIT ioctl argument type.
+ *
+ * New in DRM 1.6: userspace can request and wait on IRQ's.
  */
 typedef struct drm_radeon_irq_emit {
 	int *irq_seq;
 } drmRadeonIrqEmit;
 
+/**
+ * \brief DRM_RADEON_IRQ_WAIT ioctl argument type.
+ *
+ * New in DRM 1.6: userspace can request and wait on IRQ's.
+ */
 typedef struct drm_radeon_irq_wait {
 	int irq_seq;
 } drmRadeonIrqWait;
diff --git a/src/mesa/drivers/dri/radeon/server/radeon_dri.c b/src/mesa/drivers/dri/radeon/server/radeon_dri.c
index a9e8b53bf5..4222aae043 100644
--- a/src/mesa/drivers/dri/radeon/server/radeon_dri.c
+++ b/src/mesa/drivers/dri/radeon/server/radeon_dri.c
@@ -88,6 +88,8 @@ static unsigned int RADEONINPLL( struct MiniGLXDisplayRec *dpy, int addr)
  * \brief Reset graphics card to known state.
  *
  * \param dpy display handle.
+ *
+ * Resets the values of several Radeon registers.
  */
 static void RADEONEngineReset( struct MiniGLXDisplayRec *dpy )
 {
@@ -153,6 +155,15 @@ static void RADEONEngineReset( struct MiniGLXDisplayRec *dpy )
    OUTPLL(RADEON_MCLK_CNTL, mclk_cntl);
 }
 
+/**
+ * \brief Restore the drawing engine.
+ *
+ * \param dpy display handle
+ * \param info driver private data.
+ *
+ * Resets the graphics card and sets initial values for several registers of
+ * the card's drawing engine.
+ */
 static void RADEONEngineRestore( struct MiniGLXDisplayRec *dpy,
 				 RADEONInfoPtr info )
 
@@ -901,7 +912,6 @@ static void get_chipfamily_from_chipset( RADEONInfoPtr info )
 }
 
 
-
 /**
  * \brief Establish the set of visuals available for the display.
  *
diff --git a/src/mesa/drivers/dri/radeon/server/radeon_dri.h b/src/mesa/drivers/dri/radeon/server/radeon_dri.h
index b619fb011d..fce21227cb 100644
--- a/src/mesa/drivers/dri/radeon/server/radeon_dri.h
+++ b/src/mesa/drivers/dri/radeon/server/radeon_dri.h
@@ -62,53 +62,53 @@ typedef struct {
      * \name DRI screen private data
      */
     /*@{*/
-    int           deviceID;	/**< \brief PCI device ID */
-    int           width;	/**< \brief width in pixels of display */
-    int           height;	/**< \brief height in scanlines of display */
-    int           depth;	/**< \brief depth of display (8, 15, 16, 24) */
-    int           bpp;		/**< \brief bit depth of display (8, 16, 24, 32) */
+    int           deviceID;	 /**< \brief PCI device ID */
+    int           width;	 /**< \brief width in pixels of display */
+    int           height;	 /**< \brief height in scanlines of display */
+    int           depth;	 /**< \brief depth of display (8, 15, 16, 24) */
+    int           bpp;		 /**< \brief bit depth of display (8, 16, 24, 32) */
 
-    int           IsPCI;	/**< \brief current card is a PCI card */
-    int           AGPMode;	/**< \brief AGP mode */
+    int           IsPCI;	 /**< \brief is current card a PCI card? */
+    int           AGPMode;	 /**< \brief AGP mode */
 
-    int           frontOffset;  /**< \brief front buffer offset */
-    int           frontPitch;	/**< \brief front buffer pitch */
-    int           backOffset;   /**< \brief shared back buffer offset */
-    int           backPitch;    /**< \brief shared back buffer pitch */
-    int           depthOffset;  /**< \brief shared depth buffer offset */
-    int           depthPitch;   /**< \brief shared depth buffer pitch */
-    int           textureOffset;/**< \brief start of texture data in frame buffer */
-    int           textureSize;  /**< \brief size of texture date */
-    int           log2TexGran;  /**< \brief log2 texture granularity */
+    int           frontOffset;   /**< \brief front buffer offset */
+    int           frontPitch;	 /**< \brief front buffer pitch */
+    int           backOffset;    /**< \brief shared back buffer offset */
+    int           backPitch;     /**< \brief shared back buffer pitch */
+    int           depthOffset;   /**< \brief shared depth buffer offset */
+    int           depthPitch;    /**< \brief shared depth buffer pitch */
+    int           textureOffset; /**< \brief start of texture data in frame buffer */
+    int           textureSize;   /**< \brief size of texture date */
+    int           log2TexGran;   /**< \brief log2 texture granularity */
     /*@}*/
 
     /**
      * \name MMIO register data
      */
     /*@{*/
-    drmHandle     registerHandle;
-    drmSize       registerSize;
+    drmHandle     registerHandle; /**< \brief MMIO register map size */
+    drmSize       registerSize;   /**< \brief MMIO register map handle */
     /*@}*/
 
     /**
      * \name CP in-memory status information
      */
     /*@{*/
-    drmHandle     statusHandle;
-    drmSize       statusSize;
+    drmHandle     statusHandle;   /**< \brief status map handle */
+    drmSize       statusSize;     /**< \brief status map size */
     /*@}*/
 
     /**
      * \name CP AGP Texture data
      */
     /*@{*/
-    drmHandle     agpTexHandle;
-    drmSize       agpTexMapSize;
-    int           log2AGPTexGran;
-    int           agpTexOffset;
+    drmHandle     agpTexHandle;   /**< \brief AGP texture area map handle */
+    drmSize       agpTexMapSize;  /**< \brief AGP texture area map size */
+    int           log2AGPTexGran; /**< \brief AGP texture granularity in log base 2 */
+    int           agpTexOffset;   /**< \brief AGP texture area offset in AGP space */
     /*@}*/
 
-    unsigned int  sarea_priv_offset;
+    unsigned int  sarea_priv_offset; /**< \brief offset of the private SAREA data*/
 } RADEONDRIRec, *RADEONDRIPtr;
 
 #endif
diff --git a/src/mesa/drivers/dri/radeon/server/radeon_sarea.h b/src/mesa/drivers/dri/radeon/server/radeon_sarea.h
index 93c58f2775..fb801285f0 100644
--- a/src/mesa/drivers/dri/radeon/server/radeon_sarea.h
+++ b/src/mesa/drivers/dri/radeon/server/radeon_sarea.h
@@ -116,6 +116,9 @@
 #endif /* __RADEON_SAREA_DEFINES__ */
 
 
+/**
+ * \brief Color register format.
+ */
 typedef struct {
     unsigned int red;
     unsigned int green;
@@ -231,7 +234,7 @@ typedef struct {
  *
  * If you think you own a region of texture memory, and it has an age different
  * to the one you set, then you are mistaken and it has been stolen by another
- * client.  If global texAge hasn't changed, there is no need to walk the list.
+ * client.  If global RADEONSAREAPriv::texAge hasn't changed, there is no need to walk the list.
  *
  * These regions can be used as a proxy for the fine-grained texture
  * information of other clients - by maintaining them in the same LRU which is
@@ -243,9 +246,10 @@ typedef struct {
  * \sa RADEONSAREAPriv::texList.
  */
 typedef struct {
-    unsigned char next, prev;	/**< indices to form a circular LRU  */
-    unsigned char in_use;	/**< owned by a client, or free? */
-    int age;			/**< tracked by clients to update local LRU's */
+    unsigned char next; 	/**< \brief indices to form a circular LRU */
+    unsigned prev;		/**< \brief indices to form a circular LRU */
+    unsigned char in_use;	/**< \brief owned by a client, or free? */
+    int age;			/**< \brief tracked by clients to update local LRU's */
 } radeon_tex_region_t;
 
 
@@ -256,26 +260,28 @@ typedef struct {
  * on firing a vertex buffer.
  */
 typedef struct {
-    /** \brief Context registers */
-    radeon_context_regs_t ContextState;
-    /** \brief Texture registers */
+    radeon_context_regs_t ContextState; /** \brief Context registers */
     radeon_texture_regs_t TexState[RADEON_MAX_TEXTURE_UNITS];
-    unsigned int dirty;
-    unsigned int vertsize;
-    unsigned int vc_format;
+                                        /**< \brief Texture registers */
+    unsigned int dirty; 
+    unsigned int vertsize;              /**< \brief vertex size */
+    unsigned int vc_format;             /**< \brief vertex format */
 
     /**
      * \name Cliprects 
-     * The current cliprects, or a subset thereof 
+     *
+     * The current cliprects, or a subset thereof.
      */
     /*@{*/
-    XF86DRIClipRectRec boxes[RADEON_NR_SAREA_CLIPRECTS];
-    unsigned int nbox;
+    XF86DRIClipRectRec boxes[RADEON_NR_SAREA_CLIPRECTS]; 
+                       /**< \brief cliprects */
+    unsigned int nbox; /**< \brief number of cliprects */
     /*@}*/
 
     /**
      * \name Counters
-     * Counters for throttling of rendering clients
+     *
+     * Counters for throttling rendering of clients.
      */
     /*@{*/
     unsigned int last_frame;
@@ -287,7 +293,9 @@ typedef struct {
      * \name LRU
      */
     /*@{*/
-    /** Last elt is sentinal */
+    /** \brief Texture regions. 
+     * Last element is sentinal
+     */
     radeon_tex_region_t texList[RADEON_NR_TEX_HEAPS][RADEON_NR_TEX_REGIONS+1];
     /** \brief last time texture was uploaded */
     int texAge[RADEON_NR_TEX_HEAPS];