Just additional comments.

src/mesa/main/buffers.c

@@ -433,6 +433,11 @@ _mesa_DrawBuffersARB(GLsizei n, const GLenum *buffers)
  * output, but fragment programs can now have several distinct color
  * outputs (see GL_ARB_draw_buffers).  This function sets the state
  * for one such color output.
+ * \param ctx  current context
+ * \param output  which fragment program output
+ * \param buffer  buffer to write to (like GL_LEFT)
+ * \param destMask  BUFFER_* bitmask
+ *                  (like BUFFER_BIT_FRONT_LEFT | BUFFER_BIT_BACK_LEFT).
  */
 static void
 set_color_output(GLcontext *ctx, GLuint output, GLenum buffer, GLuint destMask)
@@ -457,6 +462,14 @@ set_color_output(GLcontext *ctx, GLuint output, GLenum buffer, GLuint destMask)
 /**
  * Helper routine used by _mesa_DrawBuffer, _mesa_DrawBuffersARB and
  * _mesa_PopAttrib to set drawbuffer state.
+ * All error checking will have been done prior to calling this function
+ * so nothing should go wrong at this point.
+ * \param ctx  current context
+ * \param n    number of color outputs to set
+ * \param buffers  array[n] of colorbuffer names, like GL_LEFT.
+ * \param destMask  array[n] of BUFFER_* bitmasks which correspond to the
+ *                  colorbuffer names.  (i.e. GL_FRONT_AND_BACK =>
+ *                  BUFFER_BIT_FRONT_LEFT | BUFFER_BIT_BACK_LEFT).
  */
 void
 _mesa_drawbuffers(GLcontext *ctx, GLsizei n, const GLenum *buffers,

src/mesa/main/framebuffer.c

@@ -460,7 +460,14 @@ get_renderbuffer(struct gl_framebuffer *fb, GLuint bufferBit)
 
 /**
  * Update state related to the current draw/read framebuffers.
+ * Specifically, update these framebuffer fields:
+ *    _ColorDrawBuffers
+ *    _ColorDrawBit
+ *    _NumColorDrawBuffers
+ *    _ColorReadBuffer
  * If the current framebuffer is user-created, make sure it's complete.
+ * The following functions can effect this state:  glReadBuffer,
+ * glDrawBuffer, glDrawBuffersARB, glFramebufferRenderbufferEXT.
  */
 void
 _mesa_update_framebuffer(GLcontext *ctx)

src/mesa/swrast/s_buffers.c

@@ -1,6 +1,6 @@
 /*
  * Mesa 3-D graphics library
- * Version:  6.3
+ * Version:  6.5
  *
  * Copyright (C) 1999-2005  Brian Paul   All Rights Reserved.
  *
@@ -349,6 +349,9 @@ _swrast_DrawBuffers( GLcontext *ctx, GLsizei n, const GLenum *buffers )
  * Setup things so that we read/write spans from the user-designated
  * read buffer (set via glReadPixels).  We usually just have to call
  * this for glReadPixels, glCopyPixels, etc.
+ *
+ * XXX this will go away when the last OLD_RENDERBUFFER code is removed.
+ * The swrast->CurrentBufferBit var can be totally removed then too.
  */
 void
 _swrast_use_read_buffer( GLcontext *ctx )
@@ -366,6 +369,9 @@ _swrast_use_read_buffer( GLcontext *ctx )
 /*
  * Setup things so that we read/write spans from the default draw buffer.
  * This is the usual mode that Mesa's software rasterizer operates in.
+ *
+ * XXX this will go away when the last OLD_RENDERBUFFER code is removed.
+ * The swrast->CurrentBufferBit var can be totally removed then too.
  */
 void
 _swrast_use_draw_buffer( GLcontext *ctx )