notes on documenting elements and plugins

Original commit message from CVS:
notes on documenting elements and plugins

common

@@ -1 +1 @@
-Subproject commit 112f70ef5172090966f53934a471eb2e54c2d667
+Subproject commit 9563779845a70c73dd9bc9ff6750b155e2b4cba2

docs/README

@@ -195,6 +195,47 @@ d) have verified your changes build documentation locally.
 Then, after updating any of the docs, run "make upload" from that directory.
 Or, run "make upload" from this (docs) directory.
 
+DOCUMENTING ELEMENTS
+====================
+As of september 2005 we have some system to document plugins and elements
+in the various plugin packages.
+
+- in a submodule, docs go in docs/plugins
+- template can be copied from gst-plugins-base
+- to add an element to be documented:
+  - add an include href in the Elements chapter for the element
+  - add a section for it in -sections.txt with
+      <FILE>element-(element)</FILE>
+      <TITLE>(element)</TITLE>
+  - add a gtk-doc section to the source code like:
+/**
+ * SECTION:element-multifdsink
+
+  and fill it with documentation about the element, preferably inside
+  a <refsect2> docbook container.
+  - add an example:
+    - either a few pipelines, inside <programlisting>
+    - or a piece of code:
+      - create an example program (element)-example.c in the plugin dir
+      - add the full path (starting with $(top_srcdir)) for this example
+        to the EXAMPLE_CFILES variable in Makefile.am
+      - add an xinclude of a file named "element-(element)-example.xml"
+        to the docbook documentation piece in the element source code
+  - add the header to EXTRA_HFILES in Makefile.am to be able to document
+    signals and args
+    (FIXME: are we sure we can both do the xinclude from the tmpl/ sgml,
+     as well as an override from the source itself ? maybe we should just
+     make sure the xinclude is in the source itself instead ?)
+  - to rebuild the docs, do:
+    make clean
+    make inspect-update
+    make
+
+- to add a plugin to be documented:
+  - make sure inspect/ has generated a .xml file for it
+  - add it to CVS
+  - add an include in -docs.sgml in the Plugins list for that plugin
+
 RANDOM THINGS I'VE LEARNED
 ==========================
 

docs/gst/tmpl/gstelement.sgml

@@ -65,9 +65,6 @@ and gst_element_set_clock().  You can wait for the clock to reach a given
 
 <!-- basic object functions -->
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### STRUCT GstElement ##### -->
 <para>
 
@@ -973,6 +970,16 @@ Sets the parent of an element.
 @Returns: 
 
 
+<!-- ##### FUNCTION gst_element_set_state_async ##### -->
+<para>
+
+</para>
+
+@element: 
+@state: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gst_element_state_get_name ##### -->
 <para>
 

docs/gst/tmpl/gstenumtypes.sgml

@@ -14,6 +14,3 @@ all gstreamer core related enumerations
 
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-

docs/gst/tmpl/gstimplementsinterface.sgml

@@ -14,9 +14,6 @@ Core interface implemented by #GstElements that allows runtime querying of inter
 
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### STRUCT GstImplementsInterface ##### -->
 <para>
 

docs/gst/tmpl/gstindex.sgml

@@ -15,9 +15,6 @@ in a pipeline.
 #GstIndexFactory
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### STRUCT GstIndex ##### -->
 <para>
 

docs/gst/tmpl/gstindexfactory.sgml

@@ -14,9 +14,6 @@ GstIndexFactory is used to dynamically create GstIndex implementations.
 #GstIndex
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### STRUCT GstIndexFactory ##### -->
 <para>
 The GstIndexFactory object

docs/gst/tmpl/gstinfo.sgml

@@ -68,9 +68,6 @@ categories. These are explained at GST_DEBUG_CATEGORY_INIT().
 and environment variables that affect the debugging output.
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### ENUM GstDebugLevel ##### -->
 <para>
 The level defines the importance of a debugging message. The more important a 

docs/gst/tmpl/gstobject.sgml

@@ -67,9 +67,6 @@ object.
 
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### STRUCT GstObject ##### -->
 <para>
 

docs/gst/tmpl/gstpad.sgml

@@ -57,9 +57,6 @@ Last reviewed on December 13th, 2002 (0.5.0.1)
 #GstPadTemplate, #GstElement, #GstEvent
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### STRUCT GstPad ##### -->
 <para>
 

docs/gst/tmpl/gstpadtemplate.sgml

@@ -73,9 +73,6 @@ The following example shows you how to add the padtemplate to an elementfactory:
 #GstPad, #GstElementFactory
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### STRUCT GstPadTemplate ##### -->
 <para>
 The padtemplate object.

docs/gst/tmpl/gstpipeline.sgml

@@ -21,9 +21,6 @@ the pipeline, use gst_object_unref() to free its resources.
 #GstBin
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### STRUCT GstPipeline ##### -->
 <para>
 

docs/gst/tmpl/gstplugin.sgml

@@ -35,9 +35,6 @@ to bring the plugin into memory.
 #GstPluginFeature, #GstType, #GstAutoplug, #GstElementFactory
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### FUNCTION gst_plugin_error_quark ##### -->
 <para>
 Get the error quark

docs/gst/tmpl/gstpluginfeature.sgml

@@ -14,9 +14,6 @@ This is a base class for anything that can be added to a #GstPlugin.
 #GstPlugin
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### STRUCT GstPluginFeature ##### -->
 <para>
 

docs/gst/tmpl/gsttypes.sgml

@@ -14,9 +14,6 @@ various global enums and constants
 
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### ENUM GstState ##### -->
 <para>
 

docs/gst/tmpl/gstvalue.sgml

@@ -14,9 +14,6 @@ GValue implementations specific to GStreamer
 
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### MACRO GST_VALUE_HOLDS_FOURCC ##### -->
 
 

docs/libs/tmpl/gstdataprotocol.sgml

@@ -27,9 +27,6 @@ network connections also need a protocol to do this.
 #GstBuffer, #GstCaps, #GstEvent
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### ENUM GstDPHeaderFlag ##### -->
 <para>
 

docs/libs/tmpl/gstgetbits.sgml

@@ -14,9 +14,6 @@ accelerated routines for getting bits from a data stream.
 
 </para>
 
-<!-- ##### SECTION Stability_Level ##### -->
-
-
 <!-- ##### STRUCT gst_getbits_t ##### -->
 <para>