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.

1 files changed, 33 insertions, 17 deletions

diff --git a/gst/gstpadtemplate.c b/gst/gstpadtemplate.c
index dc87156a5..348107b3b 100644
--- a/gst/gstpadtemplate.c
+++ b/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
- * the caps of a padtemplate. It's not possible to modify the caps of a
- * padtemplate after creation.
+ * they are capable of dealing with. gst_pad_template_get_caps() or 
+ * GST_PAD_TEMPLATE_CAPS() are used to get the caps of a padtemplate. It's not 
+ * possible to modify the caps of a padtemplate after creation.
  *
- * Padtemplates can be created with gst_pad_template_new() or with the
- * convenient GST_PAD_TEMPLATE_FACTORY() macro. A padtemplate can be used to
- * create a pad or to add to an elementfactory.
+ * PadTemplates have a #GstPadPresence property which identifies the lifetime
+ * of the pad and that can be retrieved with GST_PAD_TEMPLATE_PRESENCE(). Also 
+ * 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
- *   my_factory_init (GstPlugin *plugin)
+ *   static void
+ *   my_element_base_init (gpointer g_class)
  *   {
- *     GstElementFactory *factory;
- *     factory = gst_element_factory_new ("my_factory", GST_TYPE_MYFACTORY, &amp;gst_myfactory_details);
- *     g_return_val_if_fail (factory != NULL, FALSE);
- *     gst_element_factory_add_pad_template (factory, GST_PAD_TEMPLATE_GET (my_template_factory));
- *     gst_plugin_add_feature (plugin, GST_PLUGIN_FEATURE (factory));
- *     return TRUE;
+ *     GstElementClass *gstelement_class = GST_ELEMENT_CLASS (g_class);
+ *    
+ *     gst_element_class_add_pad_template (gstelement_class,
+ *         gst_static_pad_template_get (&amp;my_template));
  *   }
  *   </programlisting>
  * </informalexample>
+ *
+ * Last reviewed on 2006-02-14 (0.10.3)
  */
 
 #include "gst_private.h"