2 files changed, 18 insertions, 8 deletions
diff --git a/src/mesa/main/buffers.c b/src/mesa/main/buffers.c
index 2232ed0606e..92379a2335d 100644
--- a/src/mesa/main/buffers.c
+++ b/src/mesa/main/buffers.c
@@ -371,11 +371,14 @@ _mesa_ReadBuffer( GLenum mode )
 }
 
 
-/*
- * GL_MESA_resize_buffers extension
+/**
  * When this function is called, we'll ask the window system how large
- * the current window is.  If it's not what we expect, we'll have to
- * resize/reallocate the software accum/stencil/depth/alpha buffers.
+ * the current window is.  If it's a new size, we'll call the driver's
+ * ResizeBuffers function.  The driver will then resize its color buffers
+ * as needed, and maybe call the swrast's routine for reallocating
+ * swrast-managed depth/stencil/accum/etc buffers.
+ * \note This function may be called from within Mesa or called by the
+ * user directly (see the GL_MESA_resize_buffers extension).
  */
 void
 _mesa_ResizeBuffersMESA( void )
diff --git a/src/mesa/main/matrix.c b/src/mesa/main/matrix.c
index 83d2ff425ee..244b04ca40d 100644
--- a/src/mesa/main/matrix.c
+++ b/src/mesa/main/matrix.c
@@ -414,9 +414,13 @@ _mesa_Viewport( GLint x, GLint y, GLsizei width, GLsizei height )
 }
 
 
-/*
- * Define a new viewport and reallocate auxillary buffers if the size of
- * the window (color buffer) has changed.
+/**
+ * Set new viewport parameters and update derived state (the _WindowMap
+ * matrix).  Usually called from _mesa_Viewport().
+ * \note  We also call _mesa_ResizeBuffersMESA() because this is a good
+ * time to check if the window has been resized.  Many device drivers
+ * can't get direct notification from the window system of size changes
+ * so this is an ad-hoc solution to that problem.
  */
 void
 _mesa_set_viewport( GLcontext *ctx, GLint x, GLint y,
@@ -458,7 +462,10 @@ _mesa_set_viewport( GLcontext *ctx, GLint x, GLint y,
    ctx->NewState |= _NEW_VIEWPORT;
 
    /* Check if window/buffer has been resized and if so, reallocate the
-    * ancillary buffers.
+    * ancillary buffers.  This is an ad-hoc solution to detecting window
+    * size changes.  99% of all GL apps call glViewport when a window is
+    * resized so this is a good time to check for new window dims and
+    * reallocate color buffers and ancilliary buffers.
     */
    _mesa_ResizeBuffersMESA();