[cogl/wip/example-crate: 11/20] buffer: Improve the CoglBuffer API description

[Robert Bragg <rbragg src gnome org>]

commit 36c22d09e3df4575810c11efb8ddc5dc8221d5b8
Author: Robert Bragg <robert linux intel com>
Date:   Mon Jun 27 11:16:21 2011 +0100

    buffer: Improve the CoglBuffer API description
    
    This improves the gtk-doc overview for the CoglBuffer interface.

 cogl/cogl-buffer.h |   19 ++++++++++++++++---
 1 files changed, 16 insertions(+), 3 deletions(-)
---
diff --git a/cogl/cogl-buffer.h b/cogl/cogl-buffer.h
index 9d0312b..f3b3dbc 100644
--- a/cogl/cogl-buffer.h
+++ b/cogl/cogl-buffer.h
@@ -39,11 +39,24 @@ G_BEGIN_DECLS
 
 /**
  * SECTION:cogl-buffer
- * @short_description: Buffer creation and manipulation
+ * @short_description: Common buffer functions, including data upload APIs
  * @stability: Unstable
  *
- * COGL allows the creation and the manipulation of buffers. If the underlying
- * OpenGL implementation allows it, COGL will use Pixel Buffer Objects.
+ * The CoglBuffer API provides a common interface to manipulate
+ * buffers that have been allocated either via cogl_pixel_buffer_new()
+ * or cogl_attribute_buffer_new(). The API allows you to upload data
+ * to these buffers and define usage hints that help Cogl manage your
+ * buffer optimally.
+ *
+ * Data can either be uploaded by supplying a pointer and size so Cogl
+ * can copy your data, or you can mmap() a CoglBuffer and then you can
+ * copy data to the buffer directly.
+ *
+ * One of the most common uses for CoglBuffers is to upload texture
+ * data asynchronously since the ability to mmap the buffers into
+ * the CPU makes it possible for another thread to handle the IO
+ * of loading an image file and unpacking it into the mapped buffer
+ * without blocking other Cogl operations.
  */
 
 /* All of the cogl-buffer API is currently experimental so we suffix