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

4 files changed, 76 insertions, 7 deletions

diff --git a/gst/gst.c b/gst/gst.c
index 2186e3be9..bafb59d24 100644
--- 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 21aa68a96..d3176e190 100644
--- 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 d704873bf..934a4fdd8 100644
--- 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 15b26c3d3..761ad7a8e 100644
--- 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))