add short/long description docs to base classes add pushsrc to the docs remove consolidated doc fragments

Original commit message from CVS:
add short/long description docs to base classes
add pushsrc to the docs
remove consolidated doc fragments

ChangeLog

@@ -1,3 +1,22 @@
+2005-08-03  Stefan Kost  <ensonic@users.sf.net>
+
+	* docs/gst/Makefile.am:
+	* docs/gst/gstreamer-docs.sgml:
+	* docs/gst/gstreamer-sections.txt:
+	* docs/gst/gstreamer.types:
+	* docs/gst/tmpl/gstfakesrc.sgml:
+	* gst/base/README:
+	* gst/base/gstbasesink.c:
+	* gst/base/gstbasesink.h:
+	* gst/base/gstbasesrc.c:
+	* gst/base/gstbasesrc.h:
+	* gst/base/gstbasetransform.c:
+	* gst/base/gstpushsrc.c:
+	* gst/base/gstpushsrc.h:
+	  add short/long description docs to base classes
+	  add pushsrc to the docs
+	  remove consolidated doc fragments
+
 2005-08-03  Stefan Kost  <ensonic@users.sf.net>
 
 	* configure.ac:
@@ -13668,4 +13687,3 @@
                                                                                 
         * ChangeLog: moved to gstreamer/docs/random/old/ChangeLog.gstreamer
         * moved CVS to freedesktop.org
-

docs/gst/Makefile.am

@@ -51,10 +51,7 @@ FIXXREF_OPTIONS=
 HFILE_GLOB=$(DOC_SOURCE_DIR)/*.h
 CFILE_GLOB=$(DOC_SOURCE_DIR)/*.c
 
-# this is a wingo addition
+# Dependencies for the intermediate scanobj tool
-# thomasvs: another nice wingo addition would be an explanation on why
-# this is useful ;)
-
 #SCANOBJ_DEPS = $(top_builddir)/gst/elements/libgstelements.la \
 #	$(top_builddir)/gst/schedulers/libgstbasicomegascheduler.la
 SCANOBJ_DEPS = \

docs/gst/gstreamer-docs.sgml

@@ -58,6 +58,7 @@
 <!ENTITY GstBaseSrc SYSTEM "xml/gstbasesrc.xml">
 <!ENTITY GstBaseSink SYSTEM "xml/gstbasesink.xml">
 <!ENTITY GstBaseTransform SYSTEM "xml/gstbasetransform.xml">
+<!ENTITY GstPushSrc SYSTEM "xml/gstpushsrc.xml">
 
 <!ENTITY GstFakeSrc SYSTEM "xml/gstfakesrc.xml">
 <!ENTITY GstFakeSink SYSTEM "xml/gstfakesink.xml">
@@ -206,6 +207,7 @@
     &GstBaseSrc;
     &GstBaseSink;
     &GstBaseTransform;
+	&GstPushSrc;
 
   </chapter>
 

docs/gst/gstreamer-sections.txt

@@ -1631,6 +1631,89 @@ gst_xml_get_type
 <TITLE>GstEnumTypes</TITLE>
 </SECTION>
 
+# base classes
+
+<SECTION>
+<FILE>gstbasesrc</FILE>
+<TITLE>GstBaseSrc</TITLE>
+GstBaseSrc
+GstBaseSrcClass
+GstBaseSrcFlags
+
+gst_base_src_is_live
+gst_base_src_set_live
+
+GST_BASE_SRC_PAD
+<SUBSECTION Standard>
+GST_BASE_SRC
+GST_IS_BASE_SRC
+GST_TYPE_BASE_SRC
+GST_BASE_SRC_CLASS
+GST_IS_BASE_SRC_CLASS
+GST_BASE_SRC_GET_CLASS
+<SUBSECTION Private>
+gst_base_src_get_type
+</SECTION>
+
+
+<SECTION>
+<FILE>gstbasesink</FILE>
+<TITLE>GstBaseSink</TITLE>
+GstBaseSink
+GstBaseSinkClass
+
+GST_BASE_SINK_CLOCK
+GST_BASE_SINK_PAD
+
+<SUBSECTION Standard>
+GstBaseSinkClass
+GST_BASE_SINK
+GST_IS_BASE_SINK
+GST_TYPE_BASE_SINK
+GST_BASE_SINK_CLASS
+GST_IS_BASE_SINK_CLASS
+GST_BASE_SINK_GET_CLASS
+<SUBSECTION Private>
+gst_base_sink_get_type
+</SECTION>
+
+
+<SECTION>
+<FILE>gstbasetransform</FILE>
+<TITLE>GstBaseTransform</TITLE>
+GstBaseTransform
+GstBaseTransformClass
+<SUBSECTION Standard>
+GST_BASE_TRANSFORM
+GST_IS_BASE_TRANSFORM
+GST_TYPE_BASE_TRANSFORM
+GST_BASE_TRANSFORM_CLASS
+GST_IS_BASE_TRANSFORM_CLASS
+GST_BASE_TRANSFORM_GET_CLASS
+<SUBSECTION Private>
+gst_base_transform_get_type
+</SECTION>
+
+
+<SECTION>
+<FILE>gstpushsrc</FILE>
+<TITLE>GstPushSrc</TITLE>
+GstPushSrc
+GstPushSrcClass
+<SUBSECTION Standard>
+GST_PUSH_SRC
+GST_IS_PUSH_SRC
+GST_TYPE_PUSH_SRC
+GST_PUSH_SRC_CLASS
+GST_IS_PUSH_SRC_CLASS
+GST_PUSH_SRC_GET_CLASS
+<SUBSECTION Private>
+gst_push_src_get_type
+</SECTION>
+
+
+# elements
+
 <SECTION>
 <FILE>gstfakesrc</FILE>
 <TITLE>GstFakeSrc</TITLE>
@@ -1692,63 +1775,3 @@ GST_IS_FILESINK_CLASS
 <SUBSECTION Private>
 gst_file_sink_get_type
 </SECTION>
-
-<SECTION>
-<FILE>gstbasesrc</FILE>
-<TITLE>GstBaseSrc</TITLE>
-GstBaseSrc
-GstBaseSrcClass
-GstBaseSrcFlags
-
-gst_base_src_is_live
-gst_base_src_set_live
-
-GST_BASE_SRC_PAD
-<SUBSECTION Standard>
-GST_BASE_SRC
-GST_IS_BASE_SRC
-GST_TYPE_BASE_SRC
-GST_BASE_SRC_CLASS
-GST_IS_BASE_SRC_CLASS
-GST_BASE_SRC_GET_CLASS
-<SUBSECTION Private>
-gst_base_src_get_type
-</SECTION>
-
-
-<SECTION>
-<FILE>gstbasesink</FILE>
-<TITLE>GstBaseSink</TITLE>
-GstBaseSink
-GstBaseSinkClass
-
-GST_BASE_SINK_CLOCK
-GST_BASE_SINK_PAD
-
-<SUBSECTION Standard>
-GstBaseSinkClass
-GST_BASE_SINK
-GST_IS_BASE_SINK
-GST_TYPE_BASE_SINK
-GST_BASE_SINK_CLASS
-GST_IS_BASE_SINK_CLASS
-GST_BASE_SINK_GET_CLASS
-<SUBSECTION Private>
-gst_base_sink_get_type
-</SECTION>
-
-<SECTION>
-<FILE>gstbasetransform</FILE>
-<TITLE>GstBaseTransform</TITLE>
-GstBaseTransform
-GstBaseTransformClass
-<SUBSECTION Standard>
-GST_BASE_TRANSFORM
-GST_IS_BASE_TRANSFORM
-GST_TYPE_BASE_TRANSFORM
-GST_BASE_TRANSFORM_CLASS
-GST_IS_BASE_TRANSFORM_CLASS
-GST_BASE_TRANSFORM_GET_CLASS
-<SUBSECTION Private>
-gst_base_transform_get_type
-</SECTION>

docs/gst/gstreamer.types

@@ -36,10 +36,12 @@ gst_xml_get_type
 #include <gst/base/gstbasesrc.h>
 #include <gst/base/gstbasesink.h>
 #include <gst/base/gstbasetransform.h>
+#include <gst/base/gstpushsrc.h>
 
 gst_base_src_get_type
 gst_base_sink_get_type
 gst_base_transform_get_type
+gst_push_src_get_type
 
 % elements
 

docs/gst/tmpl/gstfakesrc.sgml

@@ -36,6 +36,12 @@ GstFakeSrc
 @:
 @:
 @:
+@:
+@:
+@:
+@:
+@:
+@: 
 
 <!-- ##### ARG GstFakeSrc:data ##### -->
 <para>

gst/base/README

@@ -2,41 +2,5 @@ Base classes
 ------------
 
 GstBaseSink
- 
-  Base class for sink elements.
-
-  - one sinkpad
-  - handles state changes
-  - does flushing
-  - preroll with optional preview
-  - pull/push mode
-  - EOS handling
-
   FIXME: not much point making it operate in pull mode as a generic
   base class I guess...
-
-GstBaseTransform
-
-  Base class for simple tranform filters
-
-  - one sinkpad and one srcpad
-  - possible formats on sink and source pad implemented
-    with custom transform_caps function. By default uses 
-    same format on sink and source.
-  - handles state changes
-  - does flushing
-  - push mode
-  - pull mode if transform can operate on arbitrary data
-
-GstBaseSrc
-
-  Base class for getrange based source elements
-
-  - one sinkpad
-  - handles state changes
-  - pull/push mode
-  - handles seeking/query
-
-GstPushSrc
-
-  Base class for push based source elements

gst/base/gstbasesink.c

@@ -19,6 +19,23 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstbasesink
+ * @short_description: Base class for sink elements
+ * @see_also: #GstBaseTransformc, #GstBaseSource
+ *
+ * This class is for elements that do output operations.
+ *
+ * <itemizedlist>
+ *   <listitem><para>one sinkpad</para></listitem>
+ *   <listitem><para>handles state changes</para></listitem>
+ *   <listitem><para>pull/push mode</para></listitem>
+ *   <listitem><para>handles seeking/query</para></listitem>
+ *   <listitem><para>handles preroll</para></listitem>
+ *   <listitem><para>EOS handling</para></listitem>
+ * </itemizedlist>
+ */
+
 #ifdef HAVE_CONFIG_H
 #  include "config.h"
 #endif

gst/base/gstbasesink.h

@@ -41,10 +41,6 @@ G_BEGIN_DECLS
 typedef struct _GstBaseSink GstBaseSink;
 typedef struct _GstBaseSinkClass GstBaseSinkClass;
 
-/* a base class for implementing chain based sinks
- *
- * Preroll, EOS, state changes are all handled.
- */
 struct _GstBaseSink {
   GstElement	 element;
 

gst/base/gstbasesrc.c

@@ -20,6 +20,23 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstbasesrc
+ * @short_description: Base class for getrange based source elements
+ * @see_also: #GstBaseTransformc, #GstBaseSink
+ *
+ * This class is mostly useful for elements that do byte based
+ * access to a random access resource, like files.
+ *
+ * <itemizedlist>
+ *   <listitem><para>one sinkpad</para></listitem>
+ *   <listitem><para>handles state changes</para></listitem>
+ *   <listitem><para>does flushing</para></listitem>
+ *   <listitem><para>preroll with optional preview</para></listitem>
+ *   <listitem><para>pull/push mode</para></listitem>
+ *   <listitem><para>EOS handling</para></listitem>
+ * </itemizedlist>
+ */
 
 #include <stdlib.h>
 #include <string.h>

gst/base/gstbasesrc.h

@@ -41,14 +41,6 @@ typedef enum {
   GST_BASE_SRC_FLAG_LAST         = GST_ELEMENT_FLAG_LAST + 2
 } GstBaseSrcFlags;
 
-/* base class for random access sources
- *
- * This class is mostly usefull for elements that do byte based
- * access to a random access resource, like files.
- *
- * Seeking, flushing, scheduling and sync is all handled by this
- * base class.
- */
 typedef struct _GstBaseSrc GstBaseSrc;
 typedef struct _GstBaseSrcClass GstBaseSrcClass;
 

gst/base/gstbasetransform.c

@@ -21,6 +21,28 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstbasetransform
+ * @short_description: Base class for simple tranform filters
+ * @see_also: #GstBaseSrc, #GstBaseSink
+ *
+ * This base class is for filter elements that process data.
+ *
+ * <itemizedlist>
+ *   <listitem><para>one sinkpad and one srcpad</para></listitem>
+ *   <listitem><para>
+ *      possible formats on sink and source pad implemented
+ *      with custom transform_caps function. By default uses
+ *      same format on sink and source.
+ *   </para></listitem>
+ *   <listitem><para>handles state changes</para></listitem>
+ *   <listitem><para>does flushing</para></listitem>
+ *   <listitem><para>push mode</para></listitem>
+ *   <listitem><para>
+ *       pull mode if transform can operate on arbitrary data
+ *    </para></listitem>
+ * </itemizedlist>
+*/
 
 #include <stdlib.h>
 

gst/base/gstpushsrc.c

@@ -20,6 +20,26 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstpushsrc
+ * @short_description: Base class for push based source elements
+ * @see_also: #GstBaseTransformc, #GstBaseSink
+ *
+ * This class is mostly usefull for elements that cannot do
+ * random access, or at least very slowly. The source usually
+ * prefers to push out a fixed size buffer.
+ *
+ * Classes extending this base class will usually be scheduled
+ * in a push based mode. It the peer accepts to operate without
+ * offsets and withing the limits of the allowed block size, this
+ * class can operate in getrange based mode automatically.
+ *
+ * The subclass should extend the methods from the baseclass in
+ * addition to the create method.
+ *
+ * Seeking, flushing, scheduling and sync is all handled by this
+ * base class.
+ */
 
 #include <stdlib.h>
 #include <string.h>

gst/base/gstpushsrc.h

@@ -36,23 +36,6 @@ G_BEGIN_DECLS
 #define GST_IS_PUSH_SRC(obj)  		(G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_PUSH_SRC))
 #define GST_IS_PUSH_SRC_CLASS(obj)  	(G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_PUSH_SRC))
 
-/* base class for block based sources
- *
- * This class is mostly usefull for elements that cannot do
- * random access, or at least very slowly. The source usually
- * prefers to push out a fixed size buffer.
- *
- * Classes extending this base class will usually be scheduled
- * in a push based mode. It the peer accepts to operate without
- * offsets and withing the limits of the allowed block size, this
- * class can operate in getrange based mode automatically.
- *
- * The subclass should extend the methods from the baseclass in
- * addition to the create method.
- *
- * Seeking, flushing, scheduling and sync is all handled by this
- * base class.
- */
 typedef struct _GstPushSrc GstPushSrc;
 typedef struct _GstPushSrcClass GstPushSrcClass;
 

libs/gst/base/README

@@ -2,41 +2,5 @@ Base classes
 ------------
 
 GstBaseSink
- 
-  Base class for sink elements.
-
-  - one sinkpad
-  - handles state changes
-  - does flushing
-  - preroll with optional preview
-  - pull/push mode
-  - EOS handling
-
   FIXME: not much point making it operate in pull mode as a generic
   base class I guess...
-
-GstBaseTransform
-
-  Base class for simple tranform filters
-
-  - one sinkpad and one srcpad
-  - possible formats on sink and source pad implemented
-    with custom transform_caps function. By default uses 
-    same format on sink and source.
-  - handles state changes
-  - does flushing
-  - push mode
-  - pull mode if transform can operate on arbitrary data
-
-GstBaseSrc
-
-  Base class for getrange based source elements
-
-  - one sinkpad
-  - handles state changes
-  - pull/push mode
-  - handles seeking/query
-
-GstPushSrc
-
-  Base class for push based source elements

libs/gst/base/gstbasesink.c

@@ -19,6 +19,23 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstbasesink
+ * @short_description: Base class for sink elements
+ * @see_also: #GstBaseTransformc, #GstBaseSource
+ *
+ * This class is for elements that do output operations.
+ *
+ * <itemizedlist>
+ *   <listitem><para>one sinkpad</para></listitem>
+ *   <listitem><para>handles state changes</para></listitem>
+ *   <listitem><para>pull/push mode</para></listitem>
+ *   <listitem><para>handles seeking/query</para></listitem>
+ *   <listitem><para>handles preroll</para></listitem>
+ *   <listitem><para>EOS handling</para></listitem>
+ * </itemizedlist>
+ */
+
 #ifdef HAVE_CONFIG_H
 #  include "config.h"
 #endif

libs/gst/base/gstbasesink.h

@@ -41,10 +41,6 @@ G_BEGIN_DECLS
 typedef struct _GstBaseSink GstBaseSink;
 typedef struct _GstBaseSinkClass GstBaseSinkClass;
 
-/* a base class for implementing chain based sinks
- *
- * Preroll, EOS, state changes are all handled.
- */
 struct _GstBaseSink {
   GstElement	 element;
 

libs/gst/base/gstbasesrc.c

@@ -20,6 +20,23 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstbasesrc
+ * @short_description: Base class for getrange based source elements
+ * @see_also: #GstBaseTransformc, #GstBaseSink
+ *
+ * This class is mostly useful for elements that do byte based
+ * access to a random access resource, like files.
+ *
+ * <itemizedlist>
+ *   <listitem><para>one sinkpad</para></listitem>
+ *   <listitem><para>handles state changes</para></listitem>
+ *   <listitem><para>does flushing</para></listitem>
+ *   <listitem><para>preroll with optional preview</para></listitem>
+ *   <listitem><para>pull/push mode</para></listitem>
+ *   <listitem><para>EOS handling</para></listitem>
+ * </itemizedlist>
+ */
 
 #include <stdlib.h>
 #include <string.h>

libs/gst/base/gstbasesrc.h

@@ -41,14 +41,6 @@ typedef enum {
   GST_BASE_SRC_FLAG_LAST         = GST_ELEMENT_FLAG_LAST + 2
 } GstBaseSrcFlags;
 
-/* base class for random access sources
- *
- * This class is mostly usefull for elements that do byte based
- * access to a random access resource, like files.
- *
- * Seeking, flushing, scheduling and sync is all handled by this
- * base class.
- */
 typedef struct _GstBaseSrc GstBaseSrc;
 typedef struct _GstBaseSrcClass GstBaseSrcClass;
 

libs/gst/base/gstbasetransform.c

@@ -21,6 +21,28 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstbasetransform
+ * @short_description: Base class for simple tranform filters
+ * @see_also: #GstBaseSrc, #GstBaseSink
+ *
+ * This base class is for filter elements that process data.
+ *
+ * <itemizedlist>
+ *   <listitem><para>one sinkpad and one srcpad</para></listitem>
+ *   <listitem><para>
+ *      possible formats on sink and source pad implemented
+ *      with custom transform_caps function. By default uses
+ *      same format on sink and source.
+ *   </para></listitem>
+ *   <listitem><para>handles state changes</para></listitem>
+ *   <listitem><para>does flushing</para></listitem>
+ *   <listitem><para>push mode</para></listitem>
+ *   <listitem><para>
+ *       pull mode if transform can operate on arbitrary data
+ *    </para></listitem>
+ * </itemizedlist>
+*/
 
 #include <stdlib.h>
 

libs/gst/base/gstpushsrc.c

@@ -20,6 +20,26 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstpushsrc
+ * @short_description: Base class for push based source elements
+ * @see_also: #GstBaseTransformc, #GstBaseSink
+ *
+ * This class is mostly usefull for elements that cannot do
+ * random access, or at least very slowly. The source usually
+ * prefers to push out a fixed size buffer.
+ *
+ * Classes extending this base class will usually be scheduled
+ * in a push based mode. It the peer accepts to operate without
+ * offsets and withing the limits of the allowed block size, this
+ * class can operate in getrange based mode automatically.
+ *
+ * The subclass should extend the methods from the baseclass in
+ * addition to the create method.
+ *
+ * Seeking, flushing, scheduling and sync is all handled by this
+ * base class.
+ */
 
 #include <stdlib.h>
 #include <string.h>

libs/gst/base/gstpushsrc.h

@@ -36,23 +36,6 @@ G_BEGIN_DECLS
 #define GST_IS_PUSH_SRC(obj)  		(G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_PUSH_SRC))
 #define GST_IS_PUSH_SRC_CLASS(obj)  	(G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_PUSH_SRC))
 
-/* base class for block based sources
- *
- * This class is mostly usefull for elements that cannot do
- * random access, or at least very slowly. The source usually
- * prefers to push out a fixed size buffer.
- *
- * Classes extending this base class will usually be scheduled
- * in a push based mode. It the peer accepts to operate without
- * offsets and withing the limits of the allowed block size, this
- * class can operate in getrange based mode automatically.
- *
- * The subclass should extend the methods from the baseclass in
- * addition to the create method.
- *
- * Seeking, flushing, scheduling and sync is all handled by this
- * base class.
- */
 typedef struct _GstPushSrc GstPushSrc;
 typedef struct _GstPushSrcClass GstPushSrcClass;