Fix padtemplate docs, fixes #328805.

Original commit message from CVS:
* docs/gst/gstreamer-sections.txt:
* gst/gstpadtemplate.c:
* gst/gstpadtemplate.h:
Fix padtemplate docs, fixes #328805.

ChangeLog

@@ -1,3 +1,10 @@
+2006-02-14  Wim Taymans  <wim@fluendo.com>
+
+	* docs/gst/gstreamer-sections.txt:
+	* gst/gstpadtemplate.c:
+	* gst/gstpadtemplate.h:
+	Fix padtemplate docs, fixes #328805.
+
 2006-02-14  Wim Taymans  <wim@fluendo.com>
 
 	* tools/gst-launch.c: (main):

docs/gst/gstreamer-sections.txt

@@ -1344,18 +1344,19 @@ GST_PAD_PREROLL_WAIT
 <SECTION>
 <FILE>gstpadtemplate</FILE>
 <TITLE>GstPadTemplate</TITLE>
-GstPadTemplate
 GstStaticPadTemplate
+GST_STATIC_PAD_TEMPLATE
+gst_static_pad_template_get
+gst_static_pad_template_get_caps
+GstPadTemplate
+GstPadTemplateFlags
+GstPadPresence
 GST_PAD_TEMPLATE_NAME_TEMPLATE
 GST_PAD_TEMPLATE_DIRECTION
 GST_PAD_TEMPLATE_PRESENCE
 GST_PAD_TEMPLATE_CAPS
 GST_PAD_TEMPLATE_IS_FIXED
-GstPadTemplateFlags
-GstPadPresence
 gst_pad_template_new
-gst_static_pad_template_get
-gst_static_pad_template_get_caps
 gst_pad_template_get_caps
 
 <SUBSECTION Standard>
@@ -1364,7 +1365,6 @@ GST_PAD_TEMPLATE
 GST_IS_PAD_TEMPLATE
 GST_PAD_TEMPLATE_CLASS
 GST_IS_PAD_TEMPLATE_CLASS
-GST_STATIC_PAD_TEMPLATE
 GST_TYPE_PAD_TEMPLATE
 GST_TYPE_PAD_TEMPLATE_FLAGS
 GST_TYPE_STATIC_CAPS

gst/gstpadtemplate.c

@@ -26,16 +26,32 @@
  * @see_also: #GstPad, #GstElementFactory
  *
  * Padtemplates describe the possible media types a pad or an elementfactory can
- * handle.
+ * handle. This allows for both inspection of handled types before loading the
+ * element plugin as well as identifying pads on elements that are not yet
+ * created (request or sometimes pads).
  *
  * Pad and PadTemplates have #GstCaps attached to it to describe the media type
- * they are capable of dealing with. gst_pad_template_get_caps() is used to get
+ * they are capable of dealing with. gst_pad_template_get_caps() or 
- * the caps of a padtemplate. It's not possible to modify the caps of a
+ * GST_PAD_TEMPLATE_CAPS() are used to get the caps of a padtemplate. It's not 
- * padtemplate after creation.
+ * possible to modify the caps of a padtemplate after creation.
  *
- * Padtemplates can be created with gst_pad_template_new() or with the
+ * PadTemplates have a #GstPadPresence property which identifies the lifetime
- * convenient GST_PAD_TEMPLATE_FACTORY() macro. A padtemplate can be used to
+ * of the pad and that can be retrieved with GST_PAD_TEMPLATE_PRESENCE(). Also 
- * create a pad or to add to an elementfactory.
+ * the direction of the pad can be retrieved from the #GstPadTemplate with 
+ * GST_PAD_TEMPLATE_DIRECTION().
+ *
+ * The GST_PAD_TEMPLATE_NAME_TEMPLATE () is important for GST_PAD_REQUEST pads
+ * because it has to be used as the name in the gst_element_request_pad_by_name()
+ * call to instantiate a pad from this template.
+ *
+ * Padtemplates can be created with gst_pad_template_new() or with 
+ * gst_static_pad_template_get (), which creates a #GstPadTemplate from a
+ * #GstStaticPadTemplate that can be filled with the
+ * convenient GST_STATIC_PAD_TEMPLATE() macro. 
+ *
+ * A padtemplate can be used to create a pad (see gst_pad_new_from_template() 
+ * or gst_pad_new_from_static_template ()) or to add to an element class 
+ * (see gst_element_class_add_pad_template ()).
  *
  * The following code example shows the code to create a pad from a padtemplate.
  * <example>
@@ -55,28 +71,28 @@
  *   my_method (void)
  *   {
  *     GstPad *pad;
- *     pad = gst_pad_new_from_template (GST_PAD_TEMPLATE_GET (my_template_factory), "sink");
+ *     pad = gst_pad_new_from_static_template (&amp;my_template, "sink");
  *     ...
  *   }
  *   </programlisting>
  * </example>
  *
  * The following example shows you how to add the padtemplate to an
- * elementfactory:
+ * element class, this is usually done in the base_init of the class:
  * <informalexample>
  *   <programlisting>
- *   gboolean
+ *   static void
- *   my_factory_init (GstPlugin *plugin)
+ *   my_element_base_init (gpointer g_class)
  *   {
- *     GstElementFactory *factory;
+ *     GstElementClass *gstelement_class = GST_ELEMENT_CLASS (g_class);
- *     factory = gst_element_factory_new ("my_factory", GST_TYPE_MYFACTORY, &amp;gst_myfactory_details);
+ *    
- *     g_return_val_if_fail (factory != NULL, FALSE);
+ *     gst_element_class_add_pad_template (gstelement_class,
- *     gst_element_factory_add_pad_template (factory, GST_PAD_TEMPLATE_GET (my_template_factory));
+ *         gst_static_pad_template_get (&amp;my_template));
- *     gst_plugin_add_feature (plugin, GST_PLUGIN_FEATURE (factory));
- *     return TRUE;
  *   }
  *   </programlisting>
  * </informalexample>
+ *
+ * Last reviewed on 2006-02-14 (0.10.3)
  */
 
 #include "gst_private.h"

gst/gstpadtemplate.h

@@ -157,6 +157,16 @@ struct _GstStaticPadTemplate {
   GstStaticCaps   static_caps;
 };
 
+/**
+ * GST_STATIC_PAD_TEMPLATE:
+ * @padname: the name template of pad
+ * @dir: the GstPadDirection of the pad
+ * @pres: the GstPadPresence of the pad
+ * @caps: the GstStaticCaps of the pad
+ *
+ * Convenience macro to fill the values of a GstStaticPadTemplate
+ * structure.
+ */
 #define GST_STATIC_PAD_TEMPLATE(padname, dir, pres, caps) \
 { \
   /* name_template */    padname, \