merged elementdetails docs into elementfactory docs inlined both

Original commit message from CVS:
* docs/gst/gstreamer-docs.sgml:
* docs/gst/gstreamer-sections.txt:
* docs/gst/tmpl/.cvsignore:
* docs/gst/tmpl/gstelementdetails.sgml:
* docs/gst/tmpl/gstelementfactory.sgml:
* gst/gst.c:
* gst/gstbus.c:
* gst/gstelementfactory.c:
* gst/gstelementfactory.h:
merged elementdetails docs into elementfactory docs
inlined both

diff --git a/ChangeLog b/ChangeLog
index 6f1dd74..9ae0a90 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2005-09-02  Stefan Kost  <ensonic@users.sf.net>
+
+       * docs/gst/gstreamer-docs.sgml:
+       * docs/gst/gstreamer-sections.txt:
+       * docs/gst/tmpl/.cvsignore:
+       * docs/gst/tmpl/gstelementdetails.sgml:
+       * docs/gst/tmpl/gstelementfactory.sgml:
+       * gst/gst.c:
+       * gst/gstbus.c:
+       * gst/gstelementfactory.c:
+       * gst/gstelementfactory.h:
+          merged elementdetails docs into elementfactory docs
+          inlined both
+
 2005-09-02  Andy Wingo  <wingo@pobox.com>
 
        * gst/gstelement.h: Add magical pixie dust to make glib-mkenums

diff --git a/docs/gst/gstreamer-docs.sgml b/docs/gst/gstreamer-docs.sgml
index 9449d8d..2154dc6 100644 (file)
--- a/docs/gst/gstreamer-docs.sgml
+++ b/docs/gst/gstreamer-docs.sgml
@@ -16,7 +16,6 @@
 -->
 <!ENTITY GstConfig SYSTEM "xml/gstconfig.xml">
 <!ENTITY GstElement SYSTEM "xml/gstelement.xml">
-<!ENTITY GstElementDetails SYSTEM "xml/gstelementdetails.xml">
 <!ENTITY GstElementFactory SYSTEM "xml/gstelementfactory.xml">
 <!ENTITY GstError SYSTEM "xml/gsterror.xml">
 <!ENTITY GstEvent SYSTEM "xml/gstevent.xml">
@@ -113,7 +112,6 @@
     &GstClock;
     &GstConfig;
     &GstElement;
-    &GstElementDetails;
     &GstElementFactory;
     &GstError;
     &GstEvent;

diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt
index e396980..bebceda 100644 (file)
--- a/docs/gst/gstreamer-sections.txt
+++ b/docs/gst/gstreamer-sections.txt
@@ -524,19 +524,12 @@ gst_element_flags_get_type
 
 
 <SECTION>
-<FILE>gstelementdetails</FILE>
-<TITLE>GstElementDetails</TITLE>
-GstElementDetails
-<SUBSECTION Standard>
-GST_ELEMENT_DETAILS
-GST_IS_ELEMENT_DETAILS
-</SECTION>
-
-
-<SECTION>
 <FILE>gstelementfactory</FILE>
 <TITLE>GstElementFactory</TITLE>
 GstElementFactory
+GstElementDetails
+GST_ELEMENT_DETAILS
+GST_IS_ELEMENT_DETAILS
 gst_element_register
 gst_element_factory_find
 gst_element_factory_get_element_type

diff --git a/docs/gst/tmpl/.gitignore b/docs/gst/tmpl/.gitignore
index c6a2474..d307f90 100644 (file)
--- a/docs/gst/tmpl/.gitignore
+++ b/docs/gst/tmpl/.gitignore
@@ -15,6 +15,8 @@ gstchildproxy.sgml
 gstcollectpads.sgml
 gstcompat.sgml
 gstconfig.sgml
+gstelementdetails.sgml
+gstelementfactory.sgml
 gstevent.sgml
 gsterror.sgml
 gstfakesrc.sgml

diff --git a/docs/gst/tmpl/gstelementdetails.sgml b/docs/gst/tmpl/gstelementdetails.sgml
deleted file mode 100644 (file)
index 757ebbc..0000000
--- a/docs/gst/tmpl/gstelementdetails.sgml
+++ /dev/null
@@ -1,30 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GstElementDetails
-
-<!-- ##### SECTION Short_Description ##### -->
-Defines public information about a #GstElement
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GstElementDetails ##### -->
-<para>
-This struct is used to define public information about the element.  It
-describes the element, mostly for the benefit of editors.
-</para>
-
-@longname: 
-@klass: 
-@description: 
-@author: 
-

diff --git a/docs/gst/tmpl/gstelementfactory.sgml b/docs/gst/tmpl/gstelementfactory.sgml
deleted file mode 100644 (file)
index c68b5b4..0000000
--- a/docs/gst/tmpl/gstelementfactory.sgml
+++ /dev/null
@@ -1,180 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GstElementFactory
-
-<!-- ##### SECTION Short_Description ##### -->
-Create GstElements from a factory
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-GstElementFactory is used to create instances of elements. A GstElementfactory
-can be added to a #GstPlugin as it is also a #GstPluginFeature.
-</para>
-<para>
-Use gst_element_factory_new() to create a new factory which can be added to a plugin 
-with gst_plugin_add_feature().
-</para>
-<para>
-gst_element_factory_add_pad_template() is used to add a padtemplate to the factory.
-This function will enable the application to query for elementfactories that handle
-a specific media type.
-</para>
-<para>
-Use the gst_element_factory_find() and gst_element_factory_create() functions
-to create element instances or use gst_element_factory_make() as a convenient 
-shortcut.
-</para>
-<para>
-The following code example shows you how to create a GstFileSrc element.
-</para>
-
-<para>
-  <programlisting role="C">
-  #include &lt;gst/gst.h&gt;
-
-  GstElement *src;
-  GstElementFactory *srcfactory;
-
-  gst_init(&amp;argc,&amp;argv);
-
-  srcfactory = gst_element_factory_find("filesrc");
-  g_return_if_fail(srcfactory != NULL);
-
-  src = gst_element_factory_create(srcfactory,"src");
-  g_return_if_fail(src != NULL);
-  ...
-  </programlisting>
-</para>
-<para>
-An elementfactory can be assigned a rank with gst_element_factory_set_rank() 
-so that the autopluggers can select a plugin more appropriatly
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GstElement, #GstPlugin, #GstPluginFeature, #GstPadTemplate.
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GstElementFactory ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### FUNCTION gst_element_register ##### -->
-<para>
-
-</para>
-
-@plugin: 
-@name: 
-@rank: 
-@type: 
-@Returns: 
-<!-- # Unused Parameters # -->
-@elementname: 
-
-
-<!-- ##### FUNCTION gst_element_factory_find ##### -->
-<para>
-
-</para>
-
-@name: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gst_element_factory_get_element_type ##### -->
-<para>
-
-</para>
-
-@factory: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gst_element_factory_get_longname ##### -->
-<para>
-
-</para>
-
-@factory: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gst_element_factory_get_klass ##### -->
-<para>
-
-</para>
-
-@factory: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gst_element_factory_get_description ##### -->
-<para>
-
-</para>
-
-@factory: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gst_element_factory_get_author ##### -->
-<para>
-
-</para>
-
-@factory: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gst_element_factory_get_num_pad_templates ##### -->
-<para>
-
-</para>
-
-@factory: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gst_element_factory_get_uri_type ##### -->
-<para>
-
-</para>
-
-@factory: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gst_element_factory_get_uri_protocols ##### -->
-<para>
-
-</para>
-
-@factory: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gst_element_factory_create ##### -->
-<para>
-
-</para>
-
-@factory: 
-@name: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gst_element_factory_make ##### -->
-<para>
-
-</para>
-
-@factoryname: 
-@name: 
-@Returns: 
-
-

diff --git a/gst/gst.c b/gst/gst.c
index 2186e3b..bafb59d 100644 (file)
--- a/gst/gst.c
+++ b/gst/gst.c
@@ -46,7 +46,7 @@
  *
  * <example>
  * <title>Initializing the gstreamer library</title>
- * <programlisting>
+ * <programlisting language="c">
  * int 
  * main (int argc, char *argv[])
  * {

diff --git a/gst/gstbus.c b/gst/gstbus.c
index 21aa68a..d3176e1 100644 (file)
--- a/gst/gstbus.c
+++ b/gst/gstbus.c
@@ -57,8 +57,7 @@
  * elements) again and again. One way to implement it is having one watch with a
  * low priority (see gst_add_watch_full()) that pops all messages.
  * 
- * Every #GstElement has its own bus.
- *
+ * Every #GstPipeline has one bus.
  */
 
 #include <errno.h>

diff --git a/gst/gstelementfactory.c b/gst/gstelementfactory.c
index d704873..934a4fd 100644 (file)
--- a/gst/gstelementfactory.c
+++ b/gst/gstelementfactory.c
@@ -20,6 +20,49 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA 02111-1307, USA.
  */
+/**
+ * SECTION:gstelementfactory
+ * @short_description: Create GstElements from a factory
+ * @see_also: #GstElement, #GstPlugin, #GstPluginFeature, #GstPadTemplate.
+ *
+ * GstElementFactory is used to create instances of elements. A GstElementfactory
+ * can be added to a #GstPlugin as it is also a #GstPluginFeature.
+ * 
+ * Use gst_element_factory_new() to create a new factory which can be added to a
+ * plugin with gst_plugin_add_feature().
+ * 
+ * gst_element_factory_add_pad_template() is used to add a padtemplate to the factory.
+ * This function will enable the application to query for elementfactories that handle
+ * a specific media type.
+ * 
+ * Use the gst_element_factory_find() and gst_element_factory_create() functions
+ * to create element instances or use gst_element_factory_make() as a convenient 
+ * shortcut.
+ * 
+ * The following code example shows you how to create a GstFileSrc element.
+ *
+ * <example>
+ * <title>Using an element factory</title>
+ * <programlisting language="c">
+ *   #include &lt;gst/gst.h&gt;
+ *   
+ *   GstElement *src;
+ *   GstElementFactory *srcfactory;
+ *   
+ *   gst_init(&amp;argc,&amp;argv);
+ *   
+ *   srcfactory = gst_element_factory_find("filesrc");
+ *   g_return_if_fail(srcfactory != NULL);
+ *   
+ *   src = gst_element_factory_create(srcfactory,"src");
+ *   g_return_if_fail(src != NULL);
+ *   ...
+ * </programlisting>
+ * </example>
+ * 
+ * An elementfactory can be assigned a rank with gst_element_factory_set_rank() 
+ * so that the autopluggers can select a plugin more appropriatly
+ */
 
 #include "gst_private.h"
 

diff --git a/gst/gstelementfactory.h b/gst/gstelementfactory.h
index 15b26c3..761ad7a 100644 (file)
--- a/gst/gstelementfactory.h
+++ b/gst/gstelementfactory.h
@@ -38,21 +38,48 @@ G_BEGIN_DECLS
 
 typedef struct _GstElementDetails GstElementDetails;
 
+/**
+ * GstElementDetails:
+ * @longname: long, english name
+ * @klass: type of element, as hierarchy
+ * @description: what the element is about
+ * @author: who wrote this thing?
+ *
+ * This struct defines the public information about a #GstElement. It contains
+ * meta-data about the element that is mostly for the benefit of editors.
+ */
 /* FIXME: need translatable stuff in here (how handle in registry)? */
 struct _GstElementDetails
 {
   /*< public > */
-  gchar *longname;              /* long, english name */
-  gchar *klass;                 /* type of element, as hierarchy */
-  gchar *description;           /* insights of one form or another */
-  gchar *author;                /* who wrote this thing? */
+  gchar *longname;
+  gchar *klass;
+  gchar *description;
+  gchar *author;
 
   /*< private > */
   gpointer _gst_reserved[GST_PADDING];
 };
 
+/**
+ * GST_ELEMENT_DETAILS:
+ * @longname: long, english name
+ * @klass: type of element, as hierarchy
+ * @description: what the element is about
+ * @author: who wrote this thing?
+ *
+ * Macro to initialize #GstElementDetails.
+ */
 #define GST_ELEMENT_DETAILS(longname,klass,description,author)         \
   { longname, klass, description, author, {0} }
+
+/**
+ * GST_IS_ELEMENT_DETAILS:
+ * @details: the #GstElementDetails to check
+ *
+ * Tests if element details are initialized.
+ */
+/* FIXME: what about adding '&& (*__gst_reserved==NULL)' */
 #define GST_IS_ELEMENT_DETAILS(details) (                                      \
   (details) && ((details)->longname != NULL) && ((details)->klass != NULL)     \
   && ((details)->description != NULL) && ((details)->author != NULL))