docs: Convert gtkdoc comments to markdown

Modernizing the documentation, making it simpler to read an
modify and allowing us to possibly switch to hotdoc in the
future.

3 files changed, 49 insertions, 53 deletions

diff --git a/sys/ximage/ximagesink.c b/sys/ximage/ximagesink.c
index 748dcd5dc..cf5f19c33 100644
--- a/sys/ximage/ximagesink.c
+++ b/sys/ximage/ximagesink.c
@@ -19,6 +19,7 @@
 
 /**
  * SECTION:element-ximagesink
+ * @title: ximagesink
  *
  * XImageSink renders video frames to a drawable (XWindow) on a local or remote
  * display. This element can receive a Window ID from the application through
@@ -26,27 +27,24 @@
  * drawable. If no Window ID was provided by the application, the element will
  * create its own internal window and render into it.
  *
- * <refsect2>
- * <title>Scaling</title>
- * <para>
+ * ## Scaling
+ *
  * As standard XImage rendering to a drawable is not scaled, XImageSink will use
  * reverse caps negotiation to try to get scaled video frames for the drawable.
  * This is accomplished by asking the peer pad if it accepts some different caps
  * which in most cases implies that there is a scaling element in the pipeline,
- * or that an element generating the video frames can generate them with a 
+ * or that an element generating the video frames can generate them with a
  * different geometry. This mechanism is handled during buffer allocations, for
  * each allocation request the video sink will check the drawable geometry, look
  * at the #GstXImageSink:force-aspect-ratio property, calculate the geometry of
  * desired video frames and then check that the peer pad accept those new caps.
  * If it does it will then allocate a buffer in video memory with this new
  * geometry and return it with the new caps.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Events</title>
- * <para>
+ *
+ * ## Events
+ *
  * XImageSink creates a thread to handle events coming from the drawable. There
- * are several kind of events that can be grouped in 2 big categories: input 
+ * are several kind of events that can be grouped in 2 big categories: input
  * events and window state related events. Input events will be translated to
  * navigation events and pushed upstream for other elements to react on them.
  * This includes events such as pointer moves, key press/release, clicks etc...
@@ -54,49 +52,48 @@
  * is not flowing (GST_STATE_PAUSED). That means that even when the element is
  * paused, it will receive expose events from the drawable and draw the latest
  * frame with correct borders/aspect-ratio.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Pixel aspect ratio</title>
- * <para>
+ *
+ * ## Pixel aspect ratio
+ *
  * When changing state to GST_STATE_READY, XImageSink will open a connection to
  * the display specified in the #GstXImageSink:display property or the default
- * display if nothing specified. Once this connection is open it will inspect 
- * the display configuration including the physical display geometry and 
+ * display if nothing specified. Once this connection is open it will inspect
+ * the display configuration including the physical display geometry and
  * then calculate the pixel aspect ratio. When caps negotiation will occur, the
- * video sink will set the calculated pixel aspect ratio on the caps to make 
+ * video sink will set the calculated pixel aspect ratio on the caps to make
  * sure that incoming video frames will have the correct pixel aspect ratio for
  * this display. Sometimes the calculated pixel aspect ratio can be wrong, it is
  * then possible to enforce a specific pixel aspect ratio using the
  * #GstXImageSink:pixel-aspect-ratio property.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Examples</title>
+ *
+ * ## Examples
  * |[
  * gst-launch-1.0 -v videotestsrc ! queue ! ximagesink
- * ]| A pipeline to test reverse negotiation. When the test video signal appears
+ * ]|
+ *  A pipeline to test reverse negotiation. When the test video signal appears
  * you can resize the window and see that scaled buffers of the desired size are
  * going to arrive with a short delay. This illustrates how buffers of desired
  * size are allocated along the way. If you take away the queue, scaling will
  * happen almost immediately.
  * |[
  * gst-launch-1.0 -v videotestsrc ! navigationtest ! videoconvert ! ximagesink
- * ]| A pipeline to test navigation events.
+ * ]|
+ *  A pipeline to test navigation events.
  * While moving the mouse pointer over the test signal you will see a black box
- * following the mouse pointer. If you press the mouse button somewhere on the 
+ * following the mouse pointer. If you press the mouse button somewhere on the
  * video and release it somewhere else a green box will appear where you pressed
  * the button and a red one where you released it. (The navigationtest element
  * is part of gst-plugins-good.)
  * |[
  * gst-launch-1.0 -v videotestsrc ! video/x-raw, pixel-aspect-ratio=(fraction)4/3 ! videoscale ! ximagesink
- * ]| This is faking a 4/3 pixel aspect ratio caps on video frames produced by
+ * ]|
+ *  This is faking a 4/3 pixel aspect ratio caps on video frames produced by
  * videotestsrc, in most cases the pixel aspect ratio of the display will be
- * 1/1. This means that videoscale will have to do the scaling to convert 
+ * 1/1. This means that videoscale will have to do the scaling to convert
  * incoming frames to a size that will match the display pixel aspect ratio
- * (from 320x240 to 320x180 in this case). Note that you might have to escape 
+ * (from 320x240 to 320x180 in this case). Note that you might have to escape
  * some characters for your shell like '\(fraction\)'.
- * </refsect2>
+ *
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/sys/ximage/ximagesink.h b/sys/ximage/ximagesink.h
index cc9c2224a..b16c7fb25 100644
--- a/sys/ximage/ximagesink.h
+++ b/sys/ximage/ximagesink.h
@@ -152,7 +152,7 @@ struct _GstXWindow
  * @pool_lock: used to protect the buffer pool
  * @buffer_pool: a list of #GstXImageBuffer that could be reused at next buffer
  * allocation call
- * @synchronous: used to store if XSynchronous should be used or not (for 
+ * @synchronous: used to store if XSynchronous should be used or not (for
  * debugging purpose only)
  * @keep_aspect: used to remember if reverse negotiation scaling should respect
  * aspect ratio
diff --git a/sys/xvimage/xvimagesink.c b/sys/xvimage/xvimagesink.c
index e008d09a0..9cd0da1a4 100644
--- a/sys/xvimage/xvimagesink.c
+++ b/sys/xvimage/xvimagesink.c
@@ -20,6 +20,7 @@
 
 /**
  * SECTION:element-xvimagesink
+ * @title: xvimagesink
  *
  * XvImageSink renders video frames to a drawable (XWindow) on a local display
  * using the XVideo extension. Rendering to a remote display is theoretically
@@ -30,20 +31,17 @@
  * application, the element will create its own internal window and render
  * into it.
  *
- * <refsect2>
- * <title>Scaling</title>
- * <para>
+ * ## Scaling
+ *
  * The XVideo extension, when it's available, handles hardware accelerated
  * scaling of video frames. This means that the element will just accept
  * incoming video frames no matter their geometry and will then put them to the
  * drawable scaling them on the fly. Using the #GstXvImageSink:force-aspect-ratio
  * property it is possible to enforce scaling with a constant aspect ratio,
  * which means drawing black borders around the video frame.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Events</title>
- * <para>
+ *
+ * ## Events
+ *
  * XvImageSink creates a thread to handle events coming from the drawable. There
  * are several kind of events that can be grouped in 2 big categories: input
  * events and window state related events. Input events will be translated to
@@ -53,11 +51,9 @@
  * is not flowing (GST_STATE_PAUSED). That means that even when the element is
  * paused, it will receive expose events from the drawable and draw the latest
  * frame with correct borders/aspect-ratio.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Pixel aspect ratio</title>
- * <para>
+ *
+ * ## Pixel aspect ratio
+ *
  * When changing state to GST_STATE_READY, XvImageSink will open a connection to
  * the display specified in the #GstXvImageSink:display property or the
  * default display if nothing specified. Once this connection is open it will
@@ -68,26 +64,27 @@
  * Sometimes the calculated pixel aspect ratio can be wrong, it is
  * then possible to enforce a specific pixel aspect ratio using the
  * #GstXvImageSink:pixel-aspect-ratio property.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Examples</title>
+ *
+ * ## Examples
  * |[
  * gst-launch-1.0 -v videotestsrc ! xvimagesink
- * ]| A pipeline to test hardware scaling.
+ * ]|
+ *  A pipeline to test hardware scaling.
  * When the test video signal appears you can resize the window and see that
  * video frames are scaled through hardware (no extra CPU cost). By default
  * the image will never be distorted when scaled, instead black borders will
  * be added if needed.
  * |[
  * gst-launch-1.0 -v videotestsrc ! xvimagesink force-aspect-ratio=false
- * ]| Same pipeline with #GstXvImageSink:force-aspect-ratio property set to
+ * ]|
+ *  Same pipeline with #GstXvImageSink:force-aspect-ratio property set to
  * false. You can observe that no borders are drawn around the scaled image
  * now and it will be distorted to fill the entire frame instead of respecting
  * the aspect ratio.
  * |[
  * gst-launch-1.0 -v videotestsrc ! navigationtest ! xvimagesink
- * ]| A pipeline to test navigation events.
+ * ]|
+ *  A pipeline to test navigation events.
  * While moving the mouse pointer over the test signal you will see a black box
  * following the mouse pointer. If you press the mouse button somewhere on the
  * video and release it somewhere else a green box will appear where you pressed
@@ -99,15 +96,17 @@
  * image area
  * |[
  * gst-launch-1.0 -v videotestsrc ! video/x-raw, pixel-aspect-ratio=4/3 ! xvimagesink
- * ]| This is faking a 4/3 pixel aspect ratio caps on video frames produced by
+ * ]|
+ *  This is faking a 4/3 pixel aspect ratio caps on video frames produced by
  * videotestsrc, in most cases the pixel aspect ratio of the display will be
  * 1/1. This means that XvImageSink will have to do the scaling to convert
  * incoming frames to a size that will match the display pixel aspect ratio
  * (from 320x240 to 320x180 in this case).
  * |[
  * gst-launch-1.0 -v videotestsrc ! xvimagesink hue=100 saturation=-100 brightness=100
- * ]| Demonstrates how to use the colorbalance interface.
- * </refsect2>
+ * ]|
+ *  Demonstrates how to use the colorbalance interface.
+ *
  */
 
 /* for developers: there are two useful tools : xvinfo and xvattr */