docs: convert the examples to use gtk-doc markup, instead of docbook

The gtk-doc markup is less intrusive and better handled when creating docs for
language bindings. The titles (where used) where not adding much.

gst/gstbuffer.c

@@ -33,9 +33,7 @@
  * created one will typically allocate memory for it and add it to the buffer.
  * The following example creates a buffer that can hold a given video frame
  * with a given width, height and bits per plane.
- * <example>
+ * |[
- * <title>Creating a buffer for a video frame</title>
- *   <programlisting>
  *   GstBuffer *buffer;
  *   GstMemory *memory;
  *   gint size, width, height, bpp;
@@ -45,11 +43,10 @@
  *   memory = gst_allocator_alloc (NULL, size, NULL);
  *   gst_buffer_insert_memory (buffer, -1, memory);
  *   ...
- *   </programlisting>
+ * ]|
- * </example>
  *
- * Alternatively, use gst_buffer_new_allocate()
+ * Alternatively, use gst_buffer_new_allocate() to create a buffer with
- * to create a buffer with preallocated data of a given size.
+ * preallocated data of a given size.
  *
  * Buffers can contain a list of #GstMemory objects. You can retrieve how many
  * memory objects with gst_buffer_n_memory() and you can get a pointer

gst/gstcaps.c

@@ -34,20 +34,15 @@
  * handle or produce at runtime.
  *
  * A #GstCaps can be constructed with the following code fragment:
- *
+ * |[
- * <example>
+ *   GstCaps *caps = gst_caps_new_simple ("video/x-raw",
- *  <title>Creating caps</title>
+ *      "format", G_TYPE_STRING, "I420",
- *  <programlisting>
+ *      "framerate", GST_TYPE_FRACTION, 25, 1,
- *  GstCaps *caps;
+ *      "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
- *  caps = gst_caps_new_simple ("video/x-raw",
+ *      "width", G_TYPE_INT, 320,
- *       "format", G_TYPE_STRING, "I420",
+ *      "height", G_TYPE_INT, 240,
- *       "framerate", GST_TYPE_FRACTION, 25, 1,
+ *      NULL);
- *       "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
+ * ]|
- *       "width", G_TYPE_INT, 320,
- *       "height", G_TYPE_INT, 240,
- *       NULL);
- *  </programlisting>
- * </example>
  *
  * A #GstCaps is fixed when it has no properties with ranges or lists. Use
  * gst_caps_is_fixed() to test for fixed caps. Fixed caps can be used in a

gst/gstevent.c

@@ -51,9 +51,7 @@
  * construct and use seek events.
  * To do that gst_event_new_seek() is used to create a seek event. It takes
  * the needed parameters to specify seeking time and mode.
- * <example>
+ * [[
- * <title>performing a seek on a pipeline</title>
- *   <programlisting>
  *   GstEvent *event;
  *   gboolean result;
  *   ...
@@ -69,8 +67,7 @@
  *   if (!result)
  *     g_warning ("seek failed");
  *   ...
- *   </programlisting>
+ * ]|
- * </example>
  *
  * Last reviewed on 2012-03-28 (0.11.3)
  */

gst/gstinfo.c

@@ -50,19 +50,15 @@
  * categories. This is easily done with 3 lines. At the top of your code,
  * declare
  * the variables and set the default category.
- * <informalexample>
+ * |[
- * <programlisting>
+ *   GST_DEBUG_CATEGORY_STATIC (my_category);  // define category (statically)
- * GST_DEBUG_CATEGORY_STATIC (my_category);     // define category (statically)
+ *   #define GST_CAT_DEFAULT my_category       // set as default
- * &hash;define GST_CAT_DEFAULT my_category     // set as default
+ * ]|
- * </programlisting>
- * </informalexample>
  * After that you only need to initialize the category.
- * <informalexample>
+ * |[
- * <programlisting>
+ *   GST_DEBUG_CATEGORY_INIT (my_category, "my category",
- * GST_DEBUG_CATEGORY_INIT (my_category, "my category",
+ *                            0, "This is my very own");
- *                          0, "This is my very own");
+ * ]|
- * </programlisting>
- * </informalexample>
  * Initialization must be done before the category is used first.
  * Plugins do this
  * in their plugin_init function, libraries and applications should do that

gst/gstiterator.c

@@ -37,35 +37,31 @@
  * increased.  Your code is responsible for unreffing that object after use.
  *
  * The basic use pattern of an iterator is as follows:
- *
+ * |[
- * <example>
+ *   GstIterator *it = _get_iterator(object);
- * <title>Using an iterator</title>
+ *   done = FALSE;
- *   <programlisting>
+ *   while (!done) {
- *    it = _get_iterator(object);
+ *     switch (gst_iterator_next (it, &amp;item)) {
- *    done = FALSE;
+ *       case GST_ITERATOR_OK:
- *    while (!done) {
+ *         ... use/change item here...
- *      switch (gst_iterator_next (it, &amp;item)) {
+ *         g_value_reset (&amp;item);
- *        case GST_ITERATOR_OK:
+ *         break;
- *          ... use/change item here...
+ *       case GST_ITERATOR_RESYNC:
- *          g_value_reset (&amp;item);
+ *         ...rollback changes to items...
- *          break;
+ *         gst_iterator_resync (it);
- *        case GST_ITERATOR_RESYNC:
+ *         break;
- *          ...rollback changes to items...
+ *       case GST_ITERATOR_ERROR:
- *          gst_iterator_resync (it);
+ *         ...wrong parameters were given...
- *          break;
+ *         done = TRUE;
- *        case GST_ITERATOR_ERROR:
+ *         break;
- *          ...wrong parameters were given...
+ *       case GST_ITERATOR_DONE:
- *          done = TRUE;
+ *         done = TRUE;
- *          break;
+ *         break;
- *        case GST_ITERATOR_DONE:
+ *     }
- *          done = TRUE;
+ *   }
- *          break;
+ *   g_value_unset (&amp;item);
- *      }
+ *   gst_iterator_free (it);
- *    }
+ * ]|
- *    g_value_unset (&amp;item);
- *    gst_iterator_free (it);
- *   </programlisting>
- * </example>
  *
  * Last reviewed on 2009-06-16 (0.10.24)
  */

gst/gstmessage.c

@@ -34,13 +34,9 @@
  * application using the #GstBus.
  *
  * The basic use pattern of posting a message on a #GstBus is as follows:
- *
+ * |[
- * <example>
+ *   gst_bus_post (bus, gst_message_new_eos());
- * <title>Posting a #GstMessage</title>
+ * ]|
- *   <programlisting>
- *    gst_bus_post (bus, gst_message_new_eos());
- *   </programlisting>
- * </example>
  *
  * A #GstElement usually posts messages on the bus provided by the parent
  * container using gst_element_post_message().

gst/gstpadtemplate.c

@@ -54,9 +54,7 @@
  * (see gst_element_class_add_pad_template ()).
  *
  * The following code example shows the code to create a pad from a padtemplate.
- * <example>
+ * |[
- * <title>Create a pad from a padtemplate</title>
- *   <programlisting>
  *   GstStaticPadTemplate my_template =
  *   GST_STATIC_PAD_TEMPLATE (
  *     "sink",          // the name of the pad
@@ -74,23 +72,20 @@
  *     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
  * element class, this is usually done in the class_init of the class:
- * <informalexample>
+ * |[
- *   <programlisting>
  *   static void
  *   my_element_class_init (GstMyElementClass *klass)
  *   {
  *     GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
- *
+ *   
  *     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)
  */

gst/gstquery.c

@@ -36,25 +36,20 @@
  * gst_query_parse_*() helpers.
  *
  * The following example shows how to query the duration of a pipeline:
- *
+ * |[
- * <example>
+ *   GstQuery *query;
- *  <title>Query duration on a pipeline</title>
+ *   gboolean res;
- *  <programlisting>
+ *   query = gst_query_new_duration (GST_FORMAT_TIME);
- *  GstQuery *query;
+ *   res = gst_element_query (pipeline, query);
- *  gboolean res;
+ *   if (res) {
- *  query = gst_query_new_duration (GST_FORMAT_TIME);
+ *     gint64 duration;
- *  res = gst_element_query (pipeline, query);
+ *     gst_query_parse_duration (query, NULL, &amp;duration);
- *  if (res) {
+ *     g_print ("duration = %"GST_TIME_FORMAT, GST_TIME_ARGS (duration));
- *    gint64 duration;
+ *   } else {
- *    gst_query_parse_duration (query, NULL, &amp;duration);
+ *     g_print ("duration query failed...");
- *    g_print ("duration = %"GST_TIME_FORMAT, GST_TIME_ARGS (duration));
+ *   }
- *  }
+ *   gst_query_unref (query);
- *  else {
+ * ]|
- *    g_print ("duration query failed...");
- *  }
- *  gst_query_unref (query);
- *  </programlisting>
- * </example>
  *
  * Last reviewed on 2012-03-29 (0.11.3)
  */

gst/gsttypefindfactory.c

@@ -28,9 +28,10 @@
  * the section <link linkend="gstreamer-Writing-typefind-functions">
  * "Writing typefind functions"</link>.
  *
- * <example>
+ * The following example shows how to write a very simple typefinder that
- *   <title>how to write a simple typefinder</title>
+ * identifies the given data. You can get quite a bit more complicated than
- *   <programlisting>
+ * that though.
+ * |[
  *   typedef struct {
  *     guint8 *data;
  *     guint size;
@@ -70,12 +71,7 @@
  *     g_list_free (type_list);
  *     return find.caps;
  *   };
- *   </programlisting>
+ * ]|
- * </example>
- *
- * The above example shows how to write a very simple typefinder that
- * identifies the given data. You can get quite a bit more complicated than
- * that though.
  *
  * Last reviewed on 2005-11-09 (0.9.4)
  */