add GstAdapter docs.

Original commit message from CVS:
* docs/libs/gstreamer-libs-docs.sgml:
* docs/libs/gstreamer-libs-sections.txt:
* libs/gst/bytestream/adapter.c:
add GstAdapter docs.
* libs/gst/bytestream/adapter.h:
mark custom fields in GstAdapter struct as private for gtk-doc

ChangeLog

@@ -1,3 +1,12 @@
+2005-08-04  Benjamin Otte  <otte@gnome.org>
+
+	* docs/libs/gstreamer-libs-docs.sgml:
+	* docs/libs/gstreamer-libs-sections.txt:
+	* libs/gst/bytestream/adapter.c:
+	  add GstAdapter docs.
+	* libs/gst/bytestream/adapter.h:
+	  mark custom fields in GstAdapter struct as private for gtk-doc
+
 2005-07-24  Benjamin Otte  <otte@gnome.org>
 
 	* tools/tools.h:

docs/libs/gstreamer-libs-docs.sgml

@@ -3,6 +3,7 @@
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 <!ENTITY % version-entities SYSTEM "version.entities">
 %version-entities;
+<!ENTITY GstAdapter SYSTEM "xml/gstadapter.xml">
 <!ENTITY GstBytestream SYSTEM "xml/gstbytestream.xml">
 <!ENTITY GstGetbits SYSTEM "xml/gstgetbits.xml">
 <!-- has not yet been written
@@ -36,6 +37,7 @@
     <para>
       GStreamer provides some standard libraries you can use to create plugins.
     </para>
+    &GstAdapter;
     &GstBytestream;
     &GstDataProtocol;
     &GstGetbits;

docs/libs/gstreamer-libs-sections.txt

@@ -88,6 +88,20 @@ gst_backbitsX
 swab32
 </SECTION>
 
+<SECTION>
+<FILE>gstadapter</FILE>
+<INCLUDE>gst/bytestream/adapter.h</INCLUDE>
+GstAdapter
+gst_adapter_new
+gst_adapter_clear
+gst_adapter_push
+gst_adapter_peek
+gst_adapter_flush
+gst_adapter_available
+gst_adapter_available_fast
+<SUBSECTION Standard>
+</SECTION>
+
 <SECTION>
 <FILE>gstbytestream</FILE>
 <INCLUDE>libs/bytestream/bytestream.h</INCLUDE>

libs/gst/bytestream/adapter.c

@@ -17,6 +17,47 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstadapter
+ * @short_description: object to splice and merge buffers to desired size
+ * @see_also: #GstBytestream, #GstFilePad
+ *
+ * This class is for elements that receive buffers in an undesired size. 
+ * While for example raw video contains one image per buffer, the same is not 
+ * true for a lot of other formats, especially those that come directly from 
+ * a file. So if you have undefined buffer sizes and require a specific size, 
+ * this object is for you.
+ *
+ * The theory of operation is like this: All buffers received are put
+ * into the adapter using gst_adapter_push() and the data is then read back 
+ * in chunks of the desired size using gst_adapter_peek(). After the data is
+ * processed, it is freed using gst_adapter_flush(). An example function that
+ * needs to process data in 10 byte chunks could look like this:
+ * <programlisting>
+ * void
+ * process_buffer (GstAdapter *adapter, GstBuffer *buffer)
+ * {
+ *   guint8 *data;
+ *   // put buffer into adapter
+ *   #gst_adapter_push (adapter, buffer);
+ *   // while we can read out 10 bytes, process them
+ *   while ((data = #gst_adapter_peek (adapter, 10))) {
+ *     // process the 10 bytes here
+ *     // after processing the data, flush it
+ *     #gst_adapter_flush (adapter, 10);
+ *   }
+ * }
+ * </programlisting>
+ * For another example, a simple element inside GStreamer that uses GstAdapter
+ * is the libvisual element.
+ *
+ * A last thing to note is that while GstAdapter is pretty optimized, 
+ * merging buffers still might be an operation that requires a memcpy() 
+ * operation, and this operation is not the fastest. Because of this, some 
+ * functions like gst_adapter_available_fast() are provided to help speed up 
+ * such cases should you want to.
+ */
+
 #include "adapter.h"
 #include <string.h>
 

libs/gst/bytestream/adapter.h

@@ -42,6 +42,7 @@ typedef struct _GstAdapterClass GstAdapterClass;
 struct _GstAdapter {
   GObject	object;
 
+  /*< private >*/
   GSList *	buflist;
   guint		size;
   guint		skip;