diff --git a/ChangeLog b/ChangeLog
index 5afae14999..9abb13240e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2005-11-09  Wim Taymans  <wim@fluendo.com>
+
+	* gst/gstbuffer.c:
+	* gst/gstbuffer.h:
+	Uber-spiffy-spiffify some more.
+
 2005-11-09  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* gst/base/gstcollectpads.c: (gst_collectpads_add_pad):
diff --git a/gst/gstbuffer.c b/gst/gstbuffer.c
index 30edbb7254..3a164cae2f 100644
--- a/gst/gstbuffer.c
+++ b/gst/gstbuffer.c
@@ -63,7 +63,7 @@
  * the downstream element knows the type of the buffer.
  * 
  * A buffer will usually have a timestamp, and a duration, but neither of these
- * are guaranteed (they may be set to GST_CLOCK_TIME_NONE). Whenever a 
+ * are guaranteed (they may be set to #GST_CLOCK_TIME_NONE). Whenever a 
  * meaningful value can be given for these, they should be set. The timestamp 
  * and duration are measured in nanoseconds (they are #GstClockTime values). 
  * 
@@ -74,7 +74,7 @@
  * source or destination file. Likewise, the end offset will be the offset of
  * the end of the buffer. These can only be meaningfully interpreted if you
  * know the media type of the buffer (the #GstCaps set on it). Either or both
- * can be set to GST_BUFFER_OFFSET_NONE.
+ * can be set to #GST_BUFFER_OFFSET_NONE.
  *
  * gst_buffer_ref() is used to increase the refcount of a buffer. This must be
  * done when you want to keep a handle to the buffer after pushing it to the
@@ -414,11 +414,11 @@ gst_subbuffer_init (GTypeInstance * instance, gpointer g_class)
  *          begins.
  * @size: the size of the new #GstBuffer sub-buffer, in bytes (with size > 0).
  *
- * Creates a sub-buffer from the parent at a given offset.
+ * Creates a sub-buffer from @parent at @offset and @size.
  * This sub-buffer uses the actual memory space of the parent buffer.
  * This function will copy the offset and timestamp fields when the
- * offset is 0, else they are set to GST_CLOCK_TIME_NONE/GST_BUFFER_OFFSET_NONE.
- * The duration field of the new buffer is set to GST_CLOCK_TIME_NONE.
+ * offset is 0, else they are set to #GST_CLOCK_TIME_NONE/#GST_BUFFER_OFFSET_NONE.
+ * The duration field of the new buffer is set to #GST_CLOCK_TIME_NONE.
  *
  * MT safe.
  * Returns: the new #GstBuffer.
diff --git a/gst/gstbuffer.h b/gst/gstbuffer.h
index 5602c2fd05..14f518c767 100644
--- a/gst/gstbuffer.h
+++ b/gst/gstbuffer.h
@@ -204,13 +204,36 @@ typedef enum {
   GST_BUFFER_FLAG_LAST       = (GST_MINI_OBJECT_FLAG_LAST << 8)
 } GstBufferFlag;
 
+/**
+ * GstBuffer:
+ * @mini_object: the parent structure
+ * @data: pointer to the buffer data
+ * @size: size of buffer data
+ * @timestamp: timestamp of the buffer, can be GST_CLOCK_TIME_NONE when the
+ *     timestamp is not known or relevant.
+ * @duration: duration in time of the buffer data, can be GST_CLOCK_TIME_NONE
+ *     when the duration is not known or relevant.
+ * @caps: the #GstCaps describing the data format in this buffer
+ * @offset: a media specific offset for the buffer data. 
+ *     For video frames, this is the frame number of this buffer.
+ *     For audio samples, this is the offset of the first sample in this buffer.
+ *     For file data or compressed data this is the byte offset of the first
+ *       byte in this buffer.
+ * @offset_end: the last offset contained in this buffer. It has the same 
+ *     format as @offset.
+ * @malloc_data: a pointer to the allocated memory associated with this buffer.
+ *     When the buffer is freed, this data will freed with free().
+ *
+ * The structure of a #GstBuffer. Use the associated macros to access the public
+ * variables.
+ */
 struct _GstBuffer {
   GstMiniObject		 mini_object;
 
   /*< public >*/ /* with COW */
   /* pointer to data and its size */
-  guint8		*data;			/* pointer to buffer data */
-  guint			 size;			/* size of buffer data */
+  guint8		*data;
+  guint			 size;
 
   /* timestamp */
   GstClockTime		 timestamp;
@@ -219,13 +242,7 @@ struct _GstBuffer {
   /* the media type of this buffer */
   GstCaps		*caps;
 
-  /* media specific offset
-   * for video frames, this could be the number of frames,
-   * for audio data, this could be the number of audio samples,
-   * for file data or compressed data, this could be the number of bytes
-   * offset_end is the last offset contained in the buffer. The format specifies
-   * the meaning of both of them exactly.
-   */
+  /* media specific offset */
   guint64		 offset;
   guint64		 offset_end;