More detailed documentation.

2 files changed, 403 insertions, 86 deletions

diff --git a/src/miniglx/dri_util.c b/src/miniglx/dri_util.c
index fd94afcc03e..e01ec5793df 100644
--- a/src/miniglx/dri_util.c
+++ b/src/miniglx/dri_util.c
@@ -1,4 +1,19 @@
-
+/**
+ * \file dri_util.c
+ * \brief DRI utility functions.
+ *
+ * This module acts as glue between GLX and the actual hardware driver.  A DRI
+ * driver doesn't really \e have to use any of this - it's optional.  But, some
+ * useful stuff is done here that otherwise would have to be duplicated in most
+ * drivers.
+ * 
+ * Basically, these utility functions take care of some of the dirty details of
+ * screen initialization, context creation, context binding, DRM setup, etc.
+ *
+ * These functions are compiled into each DRI driver so libGL.so knows nothing
+ * about them.
+ *
+ */
 
 #include <assert.h>
 #include <stdarg.h>
@@ -17,7 +32,12 @@
  * \brief Print message to \c stderr if the \c LIBGL_DEBUG environment variable
  * is set.
  * 
- * \note Called from drivers.
+ * Is called from the drivers.
+ * 
+ * \param f \e printf like format.
+ * 
+ * \internal
+ * Wrapper around vfprintf().
  */
 void
 __driUtilMessage(const char *f, ...)
@@ -35,10 +55,23 @@ __driUtilMessage(const char *f, ...)
 
 
 /*****************************************************************/
+/** \name Visual utility functions                               */
+/*****************************************************************/
+/*@{*/
+
 
 /**
- * Return pointer to the #__GLXvisualConfig specified by dpy, scrn and vid.
- * Return NULL if not found.
+ * \brief Find a visual.
+ * 
+ * \param dpy the display handle.
+ * \param screen the screen number. It is currently ignored and should be zero.
+ * \param vid visual ID.
+ * 
+ * \return pointer to the wanted __GLXvisualConfigRec if found, or NULL otherwise.
+ * 
+ * \internal
+ * Walks through the list of visuals in MiniGLXDisplayRec::configs until find
+ * one with a matching visual ID.
  */
 static __GLXvisualConfig *
 __driFindGlxConfig(Display *dpy, int scrn, VisualID vid)
@@ -59,7 +92,16 @@ __driFindGlxConfig(Display *dpy, int scrn, VisualID vid)
 
 
 /**
+ * \brief Convert a __GLXvisualConfigRec structure into a __GLcontextModesRec
+ * structure.
+ * 
+ * \param modes pointer to the destination __GLcontextModesRec structure.
+ * \param config pointer to the source __GLXvisualConfigRec structure.
+ * 
  * This function comes from programs/Xserver/GL/glx/glxcmds.c
+ *
+ * \internal
+ * Translates the necessary data bits from \p config to \p modes.
  */
 static void
 __glXFormatGLModes(__GLcontextModes *modes, const __GLXvisualConfig *config)
@@ -101,9 +143,35 @@ __glXFormatGLModes(__GLcontextModes *modes, const __GLXvisualConfig *config)
     modes->level = config->level;
 }
 
+/*@}*/
+
 
 /*****************************************************************/
+/** \name Context (un)binding functions                          */
+/*****************************************************************/
+/*@{*/
+
 
+/**
+ * \brief Unbind context.
+ * 
+ * \param dpy the display handle.
+ * \param scrn the screen number.
+ * \param draw drawable.
+ * \param gc context.
+ * \param will_rebind not used.
+ *
+ * \return GL_TRUE on success, or GL_FALSE on failure.
+ * 
+ * \internal
+ * Casts the opaque private pointers associated with the parameters into their
+ * respective real types while assuring they are not null. 
+ *
+ * Calls __DriverAPIRec::UnbindContext.  Decrements
+ * __DRIdrawablePrivateRec::refcount which must be non-zero for a successful
+ * return.
+ * 
+ */
 static Bool driUnbindContext(Display *dpy, int scrn,
                              GLXDrawable draw, GLXContext gc,
                              int will_rebind)
@@ -141,6 +209,22 @@ static Bool driUnbindContext(Display *dpy, int scrn,
 }
 
 
+/**
+ * \brief Unbind context.
+ * 
+ * \param dpy the display handle.
+ * \param scrn the screen number.
+ * \param draw drawable.
+ * \param gc context.
+ *
+ * \internal
+ * Casts the opaque private pointers associated with the parameters into their
+ * respective real types while assuring they are not null. 
+ *
+ * Binds the drawable to the context and increments
+ * __DRIdrawablePrivateRec::refcount and calls __DriverAPIRec::MakeCurrent.
+ * 
+ */
 static Bool driBindContext(Display *dpy, int scrn,
                             GLXDrawable draw,
                             GLXContext gc)
@@ -152,9 +236,9 @@ static Bool driBindContext(Display *dpy, int scrn,
     __DRIcontextPrivate *pcp;
 
     /*
-    ** Assume error checking is done properly in glXMakeCurrent before
-    ** calling driBindContext.
-    */
+     * Assume error checking is done properly in glXMakeCurrent before
+     * calling driBindContext.
+     */
     if (gc == NULL || draw == None) 
 	return GL_FALSE;
 
@@ -180,21 +264,40 @@ static Bool driBindContext(Display *dpy, int scrn,
     return GL_TRUE;
 }
 
+/*@}*/
 
 
 /*****************************************************************/
+/** \name Drawable handling functions                            */
+/*****************************************************************/
+/*@{*/
+
 
+/**
+ * \brief Update private drawable information.
+ *
+ * \param pdp pointer to the private drawable information to update.
+ * 
+ * \internal
+ * no-op. Should never be called, but is referenced as an external symbol from
+ * client drivers.
+ */
 void __driUtilUpdateDrawableInfo(__DRIdrawablePrivate *pdp)
 {
-   /* nothing to do, should never be called, but is referenced
-    * as an external symbol from client drivers
-    */
+   /* nothing to do */
 }
 
-/*****************************************************************/
 
 /**
+ * \brief Swap buffers.
+ *
+ * \param dpy the display handle.
+ * \param drawablePrivate opaque pointer to the per-drawable private info.
+ * 
+ * \internal
  * Called directly from glXSwapBuffers().
+ *
+ * Calls __DRIdrawablePrivate::swapBuffers.
  */
 static void driSwapBuffers( Display *dpy, void *drawablePrivate )
 {
@@ -204,6 +307,16 @@ static void driSwapBuffers( Display *dpy, void *drawablePrivate )
 }
 
 
+/**
+ * \brief Destroy per-drawable private information.
+ *
+ * \param dpy the display handle.
+ * \param drawablePrivate opaque pointer to the per-drawable private info.
+ *
+ * \internal
+ * Calls __DriverAPIRec::DestroyBuffer on \p drawablePrivate, frees the clip
+ * rects if any, and finally frees \p drawablePrivate.
+ */
 static void driDestroyDrawable(Display *dpy, void *drawablePrivate)
 {
     __DRIdrawablePrivate *pdp = (__DRIdrawablePrivate *) drawablePrivate;
@@ -219,6 +332,24 @@ static void driDestroyDrawable(Display *dpy, void *drawablePrivate)
 }
 
 
+/**
+ * \brief Create the per-drawable private driver information.
+ * 
+ * \param dpy the display handle.
+ * \param scrn the screen number.
+ * \param draw the GLX drawable info.
+ * \param pdraw will receive the drawable dependent methods.
+ *
+ * \returns a opaque pointer to the per-drawable private info on success, or NULL
+ * on failure.
+ * 
+ * \internal
+ * Allocates and fills a __DRIdrawablePrivateRec structure, initializing the
+ * invariant window dimensions and cliprects.  Gets the visual config and
+ * converts it into a __GLcontextModesRec and passes it to
+ * __DriverAPIRec::CreateBuffer to create a buffer.
+ * 
+ */
 static void *driCreateDrawable(Display *dpy, int scrn,
                                      GLXDrawable draw,
                                      VisualID vid, __DRIdrawable *pdraw)
@@ -244,7 +375,7 @@ static void *driCreateDrawable(Display *dpy, int scrn,
     pdp->display = dpy;
     pdp->screen = scrn;
 
-    /* Initialize with the invarient window dimensions and cliprects here.
+    /* Initialize with the invariant window dimensions and cliprects here.
      */
     pdp->x = 0;
     pdp->y = 0;
@@ -286,15 +417,43 @@ static void *driCreateDrawable(Display *dpy, int scrn,
     return (void *) pdp;
 }
 
+/**
+ * \brief Get the per-drawable dependent methods.
+ * 
+ * \param dpy the display handle.
+ * \param draw the GLX drawable.
+ *
+ * \return pointer to a __DRIdrawableRec structure.
+ *
+ * \internal
+ * Returns MiniGLXwindowRec::driDrawable.
+ */
 static __DRIdrawable *driGetDrawable(Display *dpy, GLXDrawable draw,
 					 void *screenPrivate)
 {
     return &draw->driDrawable;
 }
 
+/*@}*/
 
+
+/*****************************************************************/
+/** \name Context handling functions                             */
 /*****************************************************************/
+/*@{*/
+
 
+/**
+ * \brief Destroy the per-context private information.
+ * 
+ * \param dpy the display handle.
+ * \param scrn the screen number.
+ * \param contextPrivate opaque pointer to the per-drawable private info.
+ *
+ * \internal
+ * Calls __DriverAPIRec::DestroyContext on \p contextPrivate, calls
+ * drmDestroyContext(), and finally frees \p contextPrivate.
+ */
 static void driDestroyContext(Display *dpy, int scrn, void *contextPrivate)
 {
     __DRIcontextPrivate  *pcp   = (__DRIcontextPrivate *) contextPrivate;
@@ -312,6 +471,24 @@ static void driDestroyContext(Display *dpy, int scrn, void *contextPrivate)
     }
 }
 
+/**
+ * \brief Create the per-drawable private driver information.
+ * 
+ * \param dpy the display handle.
+ * \param scrn the screen number.
+ * \param vis the visual information.
+ * \param sharedPrivate the shared context dependent methods or NULL if non-existant.
+ * \param pctx will receive the context dependent methods.
+ *
+ * \returns a opaque pointer to the per-context private information on success, or NULL
+ * on failure.
+ * 
+ * \internal
+ * Allocates and fills a __DRIcontextPrivateRec structure.  Gets the visual config and
+ * converts it into a __GLcontextModesRec, passes it to
+ * __DriverAPIRec::CreateContext to create the context.
+ * 
+ */
 static void *driCreateContext(Display *dpy, XVisualInfo *vis,
                               void *sharedPrivate,
                               __DRIcontext *pctx)
@@ -371,8 +548,26 @@ static void *driCreateContext(Display *dpy, XVisualInfo *vis,
    return pcp;
 }
 
+/*@}*/
+
+
+/*****************************************************************/
+/** \name Screen handling functions                              */
 /*****************************************************************/
+/*@{*/
 
+
+/**
+ * \brief Destroy the per-screen private information.
+ * 
+ * \param dpy the display handle.
+ * \param scrn the screen number.
+ * \param screenPrivate opaque pointer to the per-screen private information.
+ *
+ * \internal
+ * Calls __DriverAPIRec::DestroyScreen on \p screenPrivate, calls
+ * drmClose(), and finally frees \p screenPrivate.
+ */
 static void driDestroyScreen(Display *dpy, int scrn, void *screenPrivate)
 {
     __DRIscreenPrivate *psp = (__DRIscreenPrivate *) screenPrivate;
@@ -390,6 +585,21 @@ static void driDestroyScreen(Display *dpy, int scrn, void *screenPrivate)
 }
 
 
+/**
+ * \brief Create the per-screen private information.
+ * 
+ * \param dpy the display handle.
+ * \param scrn the screen number.
+ * \param psc will receive the screen dependent methods.
+ *
+ * \return a pointer to the per-screen private information.
+ * 
+ * \internal
+ * Allocates and fills a __DRIscreenPrivateRec structure. Opens the DRM device
+ * verifies that the exported version matches the expected.
+ *
+ * Installs the driver callback functions and calls __DriverAPIRec::InitDriver.
+ */
 __DRIscreenPrivate *
 __driUtilCreateScreen(Display *dpy, int scrn, __DRIscreen *psc,
                       int numConfigs, __GLXvisualConfig *config,
@@ -478,7 +688,15 @@ __driUtilCreateScreen(Display *dpy, int scrn, __DRIscreen *psc,
 
 
 /**
- * Version for drivers without a drm module.
+ * \brief 
+ *
+ * Version for drivers without a DRM module.
+ * 
+ * \param dpy the display handle.
+ * \param scrn the screen number.
+ * 
+ * \internal
+ * Same as __driUtilCreateScreen() but without opening the DRM device.
  */
 __DRIscreenPrivate *
 __driUtilCreateScreenNoDRM(Display *dpy, int scrn, __DRIscreen *psc,
@@ -528,11 +746,20 @@ __driUtilCreateScreenNoDRM(Display *dpy, int scrn, __DRIscreen *psc,
 }
 
 
-/* These can be put in place and safely used prior to
- * __driUtilCreateScreen being called.  This allows glXCreateContext
- * to be called prior to XCreateWindow, but still allows XCreateWindow
- * to deterimine the virtual resolution (a screen parameter as far as
- * the driver is concerned).
+/**
+ * \brief Initialize the screen dependent methods.
+ *
+ * \param dpy the display handle.
+ * \param scrn the screen number.
+ * \param psc pointer to the screen dependent methods structure.
+ *
+ * \internal
+ * 
+ * 
+ * These can be put in place and safely used prior to __driUtilCreateScreen()
+ * being called.  This allows glXCreateContext() to be called prior to
+ * XCreateWindow(), but still allows XCreateWindow() to deterimine the virtual
+ * resolution (a screen parameter as far as the driver is concerned).
  */
 void
 __driUtilInitScreen( Display *dpy, int scrn, __DRIscreen *psc )
@@ -543,3 +770,4 @@ __driUtilInitScreen( Display *dpy, int scrn, __DRIscreen *psc )
     psc->getDrawable    = driGetDrawable;
 }
 
+/*@}*/
diff --git a/src/miniglx/dri_util.h b/src/miniglx/dri_util.h
index b51f39840a6..aca9d3d6ec7 100644
--- a/src/miniglx/dri_util.h
+++ b/src/miniglx/dri_util.h
@@ -1,6 +1,23 @@
 /**
  * \file dri_util.h
+ * \brief DRI utility functions definitions.
+ *
+ * This module acts as glue between GLX and the actual hardware driver.  A DRI
+ * driver doesn't really \e have to use any of this - it's optional.  But, some
+ * useful stuff is done here that otherwise would have to be duplicated in most
+ * drivers.
+ * 
+ * Basically, these utility functions take care of some of the dirty details of
+ * screen initialization, context creation, context binding, DRM setup, etc.
+ *
+ * These functions are compiled into each DRI driver so libGL.so knows nothing
+ * about them.
+ *
+ * Look for more comments in the dri_util.c file.
  * 
+ * \author Kevin E. Martin <kevin@precisioninsight.com>
+ * \author Brian Paul <brian@precisioninsight.com>
+ *
  * Copyright 1998-1999 Precision Insight, Inc., Cedar Park, Texas.
  * All Rights Reserved.
  * 
@@ -23,23 +40,6 @@
  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- * 
- * \author Kevin E. Martin <kevin@precisioninsight.com>
- * \author Brian Paul <brian@precisioninsight.com>
- *
- * This module acts as glue between GLX and the actual hardware driver.
- * A DRI driver doesn't really \e have to use any of this - it's optional.
- * But, some useful stuff is done here that otherwise would have to be
- * duplicated in most drivers.
- * 
- * Basically, these utility functions take care of some of the dirty details
- * of screen initialization, context creation, context binding, DRM setup,
- * etc.
- *
- * These functions are compiled into each DRI driver so libGL.so knows
- * nothing about them.
- *
- * Look for more comments in the dri_util.c file.
  */
 
 /* $XFree86$ */
@@ -50,9 +50,9 @@
 
 #define CAPI  /* XXX this should be globally defined somewhere */
 
-#include "GL/miniglx.h"           /* for GLXDrawable */
-#include "sarea.h"               /* for XF86DRISAREAPtr */
-#include "GL/internal/glcore.h"  /* for __GLcontextModes */
+#include "GL/miniglx.h"		/* for GLXDrawable */
+#include "sarea.h"		/* for XF86DRISAREAPtr */
+#include "GL/internal/glcore.h"	/* for __GLcontextModes */
 #include "miniglxP.h"		/* XID, etc */
 
 
@@ -63,6 +63,9 @@ typedef struct __DRIcontextPrivateRec  __DRIcontextPrivate;
 typedef struct __DRIdrawablePrivateRec __DRIdrawablePrivate;
 
 
+/**
+ * Used by DRI_VALIDATE_DRAWABLE_INFO
+ */
 #define DRI_VALIDATE_DRAWABLE_INFO_ONCE(pDrawPriv)              \
     do {                                                        \
 	if (*(pDrawPriv->pStamp) != pDrawPriv->lastStamp) {     \
@@ -71,6 +74,11 @@ typedef struct __DRIdrawablePrivateRec __DRIdrawablePrivate;
     } while (0)
 
 
+/**
+ * \brief Utility macro to validate the drawable information.
+ *
+ * See __DRIdrawablePrivateRec::pStamp and __DRIdrawablePrivateRec::lastStamp.
+ */
 #define DRI_VALIDATE_DRAWABLE_INFO(psp, pdp)                            \
 do {                                                                    \
     while (*(pdp->pStamp) != pdp->lastStamp) {                          \
@@ -88,6 +96,8 @@ do {                                                                    \
 
 
 /**
+ * \brief Driver callback functions.
+ *
  * Each DRI driver must have one of these structs with all the pointers set to
  * appropriate functions within the driver.
  * 
@@ -96,70 +106,127 @@ do {                                                                    \
  * this structure.
  */
 struct __DriverAPIRec {
+    /** 
+     * \brief Driver initialization callback
+     */
     GLboolean (*InitDriver)(__DRIscreenPrivate *driScrnPriv);
+    
+    /**
+     * \brief Screen destruction callback
+     */
     void (*DestroyScreen)(__DRIscreenPrivate *driScrnPriv);
+
+    /**
+     * \brief Context creation callback
+     */	    	    
     GLboolean (*CreateContext)(const __GLcontextModes *glVis,
                                __DRIcontextPrivate *driContextPriv,
                                void *sharedContextPrivate);
+
+    /**
+     * \brief Context destruction callback
+     */
     void (*DestroyContext)(__DRIcontextPrivate *driContextPriv);
+
+    /**
+     * \brief Buffer (drawable) creation callback
+     */
     GLboolean (*CreateBuffer)(__DRIscreenPrivate *driScrnPriv,
                               __DRIdrawablePrivate *driDrawPriv,
                               const __GLcontextModes *glVis,
                               GLboolean pixmapBuffer);
+    
+    /**
+     * \brief Buffer (drawable) destruction callback
+     */
     void (*DestroyBuffer)(__DRIdrawablePrivate *driDrawPriv);
+
+    /**
+     * \brief Buffer swaping callback 
+     */
     void (*SwapBuffers)(__DRIdrawablePrivate *driDrawPriv);
+
+    /**
+     * \brief Context actication callback
+     */
     GLboolean (*MakeCurrent)(__DRIcontextPrivate *driContextPriv,
                              __DRIdrawablePrivate *driDrawPriv,
                              __DRIdrawablePrivate *driReadPriv);
+
+    /**
+     * \brief Context unbinding callback
+     */
     GLboolean (*UnbindContext)(__DRIcontextPrivate *driContextPriv);
+  
+    /**
+     * \brief Full screen mode opening callback.
+     */
     GLboolean (*OpenFullScreen)(__DRIcontextPrivate *driContextPriv);
+
+    /**
+     * \brief Full screen mode closing callback.
+     */
     GLboolean (*CloseFullScreen)(__DRIcontextPrivate *driContextPriv);
 };
 
 
+/**
+ * \brief Per-drawable private DRI driver information.
+ *
+ */
 struct __DRIdrawablePrivateRec {
     /**
-     * Kernel drawable handle (not currently used).
+     * \brief Kernel drawable handle
+     *
+     * \note Not currently used.
      */
     drmDrawable hHWDrawable;
 
     /**
-     * Driver's private drawable information.  This structure is opaque.
+     * \brief Driver's private drawable information.  
+     *
+     * This structure is opaque.
      */
     void *driverPrivate;
 
     /**
-     * X's drawable ID associated with this private drawable.
+     * \brief X's drawable ID associated with this private drawable.
      */
     GLXDrawable draw;
 
     /**
-     * Reference count for number of context's currently bound to this
-     * drawable.  Once the refcount reaches 0, the drawable can be
-     * destroyed.  This behavior will change with GLX 1.3.
+     * \brief Reference count for number of context's currently bound to this
+     * drawable.  
+     *
+     * Once it reaches zero, the drawable can be destroyed.
+     *
+     * \note This behavior will change with GLX 1.3.
      */
     int refcount;
 
     /**
-     * Index of this drawable's information in the SAREA.
+     * \brief Index of this drawable's information in the SAREA.
      */
     unsigned int index;
 
     /**
-     * Pointer to the "drawable has changed ID" stamp in the SAREA.
+     * \brief Pointer to the "drawable has changed ID" stamp in the SAREA.
      */
     unsigned int *pStamp;
 
     /**
-     * Last value of the stamp.  If this differs from the value stored
-     * at *pStamp, then the drawable information has been modified by
-     * the X server, and the drawable information (below) should be
+     * \brief Last value of the stamp.
+     *
+     * If this differs from the value stored at
+     * __DRIdrawablePrivateRec::pStamp, then the drawable information has been
+     * modified by the X server, and the drawable information (below) should be
      * retrieved from the X server.
      */
     unsigned int lastStamp;
 
     /**
-     * \name Drawable information used in software fallbacks.
+     * \name Drawable 
+     * Drawable information used in software fallbacks.
      */
     /*@{*/
     int x;
@@ -171,8 +238,8 @@ struct __DRIdrawablePrivateRec {
     /*@}*/
 
     /**
-     * Information about the back and depthbuffer where different
-     * from above.
+     * \name Back and depthbuffer
+     * Information about the back and depthbuffer where different from above.
      */
     /*@{*/
     int backX;
@@ -183,78 +250,88 @@ struct __DRIdrawablePrivateRec {
     /*@}*/
 
     /**
-     * Pointer to context to which this drawable is currently bound.
+     * \brief Pointer to context to which this drawable is currently bound.
      */
     __DRIcontextPrivate *driContextPriv;
 
     /**
-     * Pointer to screen on which this drawable was created.
+     * \brief Pointer to screen on which this drawable was created.
      */
     __DRIscreenPrivate *driScreenPriv;
 
     /**
+     * \name 
      * Basically just need these for when the locking code needs to call
      * __driUtilUpdateDrawableInfo() which calls XF86DRIGetDrawableInfo().
      */
+    /*@{*/
     Display *display;
     int screen;
+    /*@}*/
 
     /**
-     * Called via glXSwapBuffers().
+     * \brief Called via glXSwapBuffers().
      */
     void (*swapBuffers)( __DRIdrawablePrivate *dPriv );
 };
 
+/**
+ * \brief Per-context private driver information.
+ */
 struct __DRIcontextPrivateRec {
     /**
-     * Kernel context handle used to access the device lock.
+     * \brief Kernel context handle used to access the device lock.
      */
     XID contextID;
 
     /**
-     * Kernel context handle used to access the device lock.
+     * \brief Kernel context handle used to access the device lock.
      */
     drmContext hHWContext;
 
     /**
-     * Device driver's private context data.  This structure is opaque.
+     * \brief Device driver's private context data.  This structure is opaque.
      */
     void *driverPrivate;
 
     /**
-     * This context's display pointer.
+     * \brief This context's display pointer.
      */
     Display *display;
 
     /**
-     * Pointer to drawable currently bound to this context.
+     * \brief Pointer to drawable currently bound to this context.
      */
     __DRIdrawablePrivate *driDrawablePriv;
 
     /**
-     * Pointer to screen on which this context was created.
+     * \brief Pointer to screen on which this context was created.
      */
     __DRIscreenPrivate *driScreenPriv;
 };
 
+/**
+ * \brief Per-screen private driver information.
+ */
 struct __DRIscreenPrivateRec {
     /**
-     * Display for this screen
+     * \brief Display for this screen
      */
     Display *display;
 
     /**
-     * Current screen's number
+     * \brief Current screen's number
      */
     int myNum;
 
     /**
-     * Callback functions into the hardware-specific DRI driver code.
+     * \brief Callback functions into the hardware-specific DRI driver code.
      */
     struct __DriverAPIRec DriverAPI;
 
     /**
-     * \name DDX / 2D driver version information.
+     * \name DDX version
+     * DDX / 2D driver version information.
      */
     /*@{*/
     int ddxMajor;
@@ -263,7 +340,8 @@ struct __DRIscreenPrivateRec {
     /*@}*/
 
     /**
-     * \name DRI X extension version information.
+     * \name DRI version
+     * DRI X extension version information.
      */
     /*@{*/
     int driMajor;
@@ -272,7 +350,8 @@ struct __DRIscreenPrivateRec {
     /*@}*/
 
     /**
-     * \name DRM (kernel module) version information.
+     * \name DRM version
+     * DRM (kernel module) version information.
      */
     /*@{*/
     int drmMajor;
@@ -281,15 +360,17 @@ struct __DRIscreenPrivateRec {
     /*@}*/
 
     /**
-     * ID used when the client sets the drawable lock.  The X server
-     * uses this value to detect if the client has died while holding
-     * the drawable lock.
+     * \brief ID used when the client sets the drawable lock.
+     *
+     * The X server uses this value to detect if the client has died while
+     * holding the drawable lock.
      */
     int drawLockID;
 
     /**
-     * File descriptor returned when the kernel device driver is opened.
-     * It is used to:
+     * \brief File descriptor returned when the kernel device driver is opened.
+     * 
+     * Used to:
      *   - authenticate client to kernel
      *   - map the frame buffer, SAREA, etc.
      *   - close the kernel device driver
@@ -297,15 +378,17 @@ struct __DRIscreenPrivateRec {
     int fd;
 
     /**
-     * SAREA pointer used to access:
+     * \brief SAREA pointer 
+     *
+     * Used to access:
      *   - the device lock
      *   - the device-independent per-drawable and per-context(?) information
      */
     XF86DRISAREAPtr pSAREA;
 
     /**
-     * \name Direct frame buffer access information used for software
-     * fallbacks.
+     * \name Direct frame buffer access information 
+     * Used for software fallbacks.
      */
     /*@{*/
     unsigned char *pFB;
@@ -328,38 +411,44 @@ struct __DRIscreenPrivateRec {
     /*@}*/
 
     /**
-     * Dummy context to which drawables are bound when not bound to any
-     * other context. A dummy hHWContext is created for this context,
-     * and is used by the GL core when a HW lock is required but the
-     * drawable is not currently bound (e.g., potentially during a
-     * SwapBuffers request).  The dummy context is created when the
-     * first "real" context is created on this screen.
+     * \brief Dummy context to which drawables are bound when not bound to any
+     * other context. 
+     *
+     * A dummy hHWContext is created for this context, and is used by the GL
+     * core when a HW lock is required but the drawable is not currently bound
+     * (e.g., potentially during a SwapBuffers request).  The dummy context is
+     * created when the first "real" context is created on this screen.
      */
     __DRIcontextPrivate dummyContextPriv;
 
     /**
-     * Hash table to hold the drawable information for this screen.
+     * \brief Hash table to hold the drawable information for this screen.
      */
     void *drawHash;
 
     /**
-     * Device-dependent private information (not stored in the SAREA).
+     * \brief Device-dependent private information (not stored in the SAREA).
+     * 
      * This pointer is never touched by the DRI layer.
      */
     void *private;
 
     /**
+     * \brief Full screen mode.
+     *
      * If we're in full screen mode (via DRIOpenFullScreen()), this points to
      * the drawable that was bound.  Otherwise, this is NULL.
      */
     __DRIdrawablePrivate *fullscreen;
 
     /**
-     * \name Number of visuals (configs) for this screen, and a pointer to them.
+     * \name Visuals 
+     *
+     * Visuals (configs) in this screen.
      */
     /*@{*/
-    int numConfigs;
-    __GLXvisualConfig *configs;
+    int numConfigs;		/**< \brief Number of visuals. */
+    __GLXvisualConfig *configs;	/**< \brief Visuals list pointer. */
     /*@}*/
 };