From c068b225fef5a9bf070673d15a0b472f41f80908 Mon Sep 17 00:00:00 2001 From: Stefan Sauer Date: Thu, 27 Feb 2014 18:06:56 +0100 Subject: [PATCH] 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 | 11 +++----- gst/gstcaps.c | 23 +++++++---------- gst/gstevent.c | 7 ++---- gst/gstinfo.c | 20 ++++++--------- gst/gstiterator.c | 54 +++++++++++++++++++--------------------- gst/gstmessage.c | 10 +++----- gst/gstpadtemplate.c | 15 ++++------- gst/gstquery.c | 33 +++++++++++------------- gst/gsttypefindfactory.c | 14 ++++------- 9 files changed, 75 insertions(+), 112 deletions(-) diff --git a/gst/gstbuffer.c b/gst/gstbuffer.c index b35fd7c071..9204e3d8b1 100644 --- a/gst/gstbuffer.c +++ b/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. - * - * Creating a buffer for a video frame - * + * |[ * 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); * ... - * - * + * ]| * - * Alternatively, use gst_buffer_new_allocate() - * to create a buffer with preallocated data of a given size. + * Alternatively, use gst_buffer_new_allocate() to create a buffer with + * 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 diff --git a/gst/gstcaps.c b/gst/gstcaps.c index 9106f9f88f..57272e27d6 100644 --- a/gst/gstcaps.c +++ b/gst/gstcaps.c @@ -34,20 +34,15 @@ * handle or produce at runtime. * * A #GstCaps can be constructed with the following code fragment: - * - * - * Creating caps - * - * GstCaps *caps; - * caps = gst_caps_new_simple ("video/x-raw", - * "format", G_TYPE_STRING, "I420", - * "framerate", GST_TYPE_FRACTION, 25, 1, - * "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1, - * "width", G_TYPE_INT, 320, - * "height", G_TYPE_INT, 240, - * NULL); - * - * + * |[ + * GstCaps *caps = gst_caps_new_simple ("video/x-raw", + * "format", G_TYPE_STRING, "I420", + * "framerate", GST_TYPE_FRACTION, 25, 1, + * "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1, + * "width", G_TYPE_INT, 320, + * "height", G_TYPE_INT, 240, + * NULL); + * ]| * * 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 diff --git a/gst/gstevent.c b/gst/gstevent.c index 377706e02e..ab13cd2d66 100644 --- a/gst/gstevent.c +++ b/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. - * - * performing a seek on a pipeline - * + * [[ * GstEvent *event; * gboolean result; * ... @@ -69,8 +67,7 @@ * if (!result) * g_warning ("seek failed"); * ... - * - * + * ]| * * Last reviewed on 2012-03-28 (0.11.3) */ diff --git a/gst/gstinfo.c b/gst/gstinfo.c index 54d7a6c32e..1d05cac061 100644 --- a/gst/gstinfo.c +++ b/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. - * - * - * GST_DEBUG_CATEGORY_STATIC (my_category); // define category (statically) - * &hash;define GST_CAT_DEFAULT my_category // set as default - * - * + * |[ + * GST_DEBUG_CATEGORY_STATIC (my_category); // define category (statically) + * #define GST_CAT_DEFAULT my_category // set as default + * ]| * After that you only need to initialize the category. - * - * - * GST_DEBUG_CATEGORY_INIT (my_category, "my category", - * 0, "This is my very own"); - * - * + * |[ + * GST_DEBUG_CATEGORY_INIT (my_category, "my category", + * 0, "This is my very own"); + * ]| * Initialization must be done before the category is used first. * Plugins do this * in their plugin_init function, libraries and applications should do that diff --git a/gst/gstiterator.c b/gst/gstiterator.c index 92d4f5f9bb..ffef504ea3 100644 --- a/gst/gstiterator.c +++ b/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: - * - * - * Using an iterator - * - * it = _get_iterator(object); - * done = FALSE; - * while (!done) { - * switch (gst_iterator_next (it, &item)) { - * case GST_ITERATOR_OK: - * ... use/change item here... - * g_value_reset (&item); - * break; - * case GST_ITERATOR_RESYNC: - * ...rollback changes to items... - * gst_iterator_resync (it); - * break; - * case GST_ITERATOR_ERROR: - * ...wrong parameters were given... - * done = TRUE; - * break; - * case GST_ITERATOR_DONE: - * done = TRUE; - * break; - * } - * } - * g_value_unset (&item); - * gst_iterator_free (it); - * - * + * |[ + * GstIterator *it = _get_iterator(object); + * done = FALSE; + * while (!done) { + * switch (gst_iterator_next (it, &item)) { + * case GST_ITERATOR_OK: + * ... use/change item here... + * g_value_reset (&item); + * break; + * case GST_ITERATOR_RESYNC: + * ...rollback changes to items... + * gst_iterator_resync (it); + * break; + * case GST_ITERATOR_ERROR: + * ...wrong parameters were given... + * done = TRUE; + * break; + * case GST_ITERATOR_DONE: + * done = TRUE; + * break; + * } + * } + * g_value_unset (&item); + * gst_iterator_free (it); + * ]| * * Last reviewed on 2009-06-16 (0.10.24) */ diff --git a/gst/gstmessage.c b/gst/gstmessage.c index 287a8362b7..1402a67989 100644 --- a/gst/gstmessage.c +++ b/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: - * - * - * Posting a #GstMessage - * - * gst_bus_post (bus, gst_message_new_eos()); - * - * + * |[ + * gst_bus_post (bus, gst_message_new_eos()); + * ]| * * A #GstElement usually posts messages on the bus provided by the parent * container using gst_element_post_message(). diff --git a/gst/gstpadtemplate.c b/gst/gstpadtemplate.c index c7c4914481..c64f9a0e23 100644 --- a/gst/gstpadtemplate.c +++ b/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. - * - * Create a pad from a padtemplate - * + * |[ * GstStaticPadTemplate my_template = * GST_STATIC_PAD_TEMPLATE ( * "sink", // the name of the pad @@ -74,23 +72,20 @@ * pad = gst_pad_new_from_static_template (&my_template, "sink"); * ... * } - * - * + * ]| * * 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: - * - * + * |[ * 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 (&my_template)); * } - * - * + * ]| * * Last reviewed on 2006-02-14 (0.10.3) */ diff --git a/gst/gstquery.c b/gst/gstquery.c index 2de6fe3826..64903b7619 100644 --- a/gst/gstquery.c +++ b/gst/gstquery.c @@ -36,25 +36,20 @@ * gst_query_parse_*() helpers. * * The following example shows how to query the duration of a pipeline: - * - * - * Query duration on a pipeline - * - * GstQuery *query; - * gboolean res; - * query = gst_query_new_duration (GST_FORMAT_TIME); - * res = gst_element_query (pipeline, query); - * if (res) { - * gint64 duration; - * gst_query_parse_duration (query, NULL, &duration); - * g_print ("duration = %"GST_TIME_FORMAT, GST_TIME_ARGS (duration)); - * } - * else { - * g_print ("duration query failed..."); - * } - * gst_query_unref (query); - * - * + * |[ + * GstQuery *query; + * gboolean res; + * query = gst_query_new_duration (GST_FORMAT_TIME); + * res = gst_element_query (pipeline, query); + * if (res) { + * gint64 duration; + * gst_query_parse_duration (query, NULL, &duration); + * g_print ("duration = %"GST_TIME_FORMAT, GST_TIME_ARGS (duration)); + * } else { + * g_print ("duration query failed..."); + * } + * gst_query_unref (query); + * ]| * * Last reviewed on 2012-03-29 (0.11.3) */ diff --git a/gst/gsttypefindfactory.c b/gst/gsttypefindfactory.c index 92eb52bc10..de4f4938bd 100644 --- a/gst/gsttypefindfactory.c +++ b/gst/gsttypefindfactory.c @@ -28,9 +28,10 @@ * the section * "Writing typefind functions". * - * - * how to write a simple typefinder - * + * The following 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. + * |[ * typedef struct { * guint8 *data; * guint size; @@ -70,12 +71,7 @@ * g_list_free (type_list); * return find.caps; * }; - * - * - * - * 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) */