[gtk/ebassi/gidocgen] video: Convert docs

[Matthias Clasen <matthiasc src gnome org>]

commit 4681b8b8db2dc0fcaa9c72a7ab0eda9c8e6dae06
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Feb 19 23:33:24 2021 -0500

    video: Convert docs
    
    Change link syntax, add an example image, generally clean things up.

 gtk/gtkvideo.c | 115 +++++++++++++++++++++++++++++----------------------------
 1 file changed, 59 insertions(+), 56 deletions(-)
---
diff --git a/gtk/gtkvideo.c b/gtk/gtkvideo.c
index f5b6f303e0..8369a296f0 100644
--- a/gtk/gtkvideo.c
+++ b/gtk/gtkvideo.c
@@ -38,17 +38,19 @@
  * @short_description: A widget for displaying video
  * @see_also: #GtkMediaControls, #GtkMediaStream
  *
- * GtkVideo is a widget to show a #GtkMediaStream with media controls
- * as provided by #GtkMediaControls. If you just want to display a
- * video without controls, you can treat it like any other paintable
- * and for example put it into a #GtkPicture.
+ * `GtkVideo` is a widget to show a `GtkMediaStream` with media controls.
  *
- * GtkVideo aims to cover use cases such as previews, embedded animations,
+ * ![An example GtkVideo](video.png)
+ *
+ * If you just want to display a video without controls, you can treat it
+ * like any other paintable and for example put it into a [class@Gtk.Picture].
+ *
+ * `GtkVideo` aims to cover use cases such as previews, embedded animations,
  * etc. It supports autoplay, looping, and simple media controls. It does
  * not have support for video overlays, multichannel audio, device
  * selection, or input. If you are writing a full-fledged video player,
- * you may want to use the #GdkPaintable API and a media framework such
- * as Gstreamer directly.
+ * you may want to use the [class@Gdk.Paintable] API and a media framework
+ * such as Gstreamer directly.
  */
 
 struct _GtkVideo
@@ -367,10 +369,10 @@ gtk_video_init (GtkVideo *self)
 /**
  * gtk_video_new:
  *
- * Creates a new empty #GtkVideo.
+ * Creates a new empty `GtkVideo`.
  *
- * Returns: a new #GtkVideo
- **/
+ * Returns: a new `GtkVideo`
+ */
 GtkWidget *
 gtk_video_new (void)
 {
@@ -379,12 +381,12 @@ gtk_video_new (void)
 
 /**
  * gtk_video_new_for_media_stream:
- * @stream: (allow-none): a #GtkMediaStream
+ * @stream: (allow-none): a `GtkMediaStream`
  *
- * Creates a #GtkVideo to play back the given @stream.
+ * Creates a `GtkVideo` to play back the given @stream.
  *
- * Returns: a new #GtkVideo
- **/
+ * Returns: a new `GtkVideo`
+ */
 GtkWidget *
 gtk_video_new_for_media_stream (GtkMediaStream *stream)
 {
@@ -397,12 +399,12 @@ gtk_video_new_for_media_stream (GtkMediaStream *stream)
 
 /**
  * gtk_video_new_for_file:
- * @file: (allow-none): a #GFile
+ * @file: (allow-none): a `GFile`
  *
- * Creates a #GtkVideo to play back the given @file.
+ * Creates a `GtkVideo` to play back the given @file.
  *
- * Returns: a new #GtkVideo
- **/
+ * Returns: a new `GtkVideo`
+ */
 GtkWidget *
 gtk_video_new_for_file (GFile *file)
 {
@@ -417,13 +419,13 @@ gtk_video_new_for_file (GFile *file)
  * gtk_video_new_for_filename:
  * @filename: (allow-none) (type filename): filename to play back
  *
- * Creates a #GtkVideo to play back the given @filename.
+ * Creates a `GtkVideo` to play back the given @filename.
  *
- * This is a utility function that calls gtk_video_new_for_file(),
+ * This is a utility function that calls [ctor@Gtk.Video.new_for_file],
  * See that function for details.
  *
- * Returns: a new #GtkVideo
- **/
+ * Returns: a new `GtkVideo`
+ */
 GtkWidget *
 gtk_video_new_for_filename (const char *filename)
 {
@@ -447,13 +449,13 @@ gtk_video_new_for_filename (const char *filename)
  * gtk_video_new_for_resource:
  * @resource_path: (allow-none): resource path to play back
  *
- * Creates a #GtkVideo to play back the resource at the
+ * Creates a `GtkVideo` to play back the resource at the
  * given @resource_path.
  *
- * This is a utility function that calls gtk_video_new_for_file(),
+ * This is a utility function that calls [ctor@Gtk.Video.new_for_file].
  *
- * Returns: a new #GtkVideo
- **/
+ * Returns: a new `GtkVideo`
+ */
 GtkWidget *
 gtk_video_new_for_resource (const char *resource_path)
 {
@@ -487,12 +489,12 @@ gtk_video_new_for_resource (const char *resource_path)
 
 /**
  * gtk_video_get_media_stream:
- * @self: a #GtkVideo
+ * @self: a `GtkVideo`
  *
  * Gets the media stream managed by @self or %NULL if none.
  *
  * Returns: (nullable) (transfer none): The media stream managed by @self
- **/
+ */
 GtkMediaStream *
 gtk_video_get_media_stream (GtkVideo *self)
 {
@@ -578,16 +580,18 @@ gtk_video_notify_cb (GtkMediaStream *stream,
 
 /**
  * gtk_video_set_media_stream:
- * @self: a #GtkVideo
+ * @self: a `GtkVideo`
  * @stream: (allow-none): The media stream to play or %NULL to unset
  *
- * Sets the media stream to be played back. @self will take full control
- * of managing the media stream. If you want to manage a media stream
- * yourself, consider using a #GtkImage for display.
+ * Sets the media stream to be played back.
  *
- * If you want to display a file, consider using gtk_video_set_file()
+ * @self will take full control of managing the media stream. If you
+ * want to manage a media stream yourself, consider using a
+ * [class@Gtk.Picture] for display.
+ *
+ * If you want to display a file, consider using [method@Gtk.Video.set_file]
  * instead.
- **/
+ */
 void
 gtk_video_set_media_stream (GtkVideo       *self,
                             GtkMediaStream *stream)
@@ -647,13 +651,13 @@ gtk_video_set_media_stream (GtkVideo       *self,
 
 /**
  * gtk_video_get_file:
- * @self: a #GtkVideo
+ * @self: a `GtkVideo`
  *
  * Gets the file played by @self or %NULL if not playing back
  * a file.
  *
  * Returns: (nullable) (transfer none): The file played by @self
- **/
+ */
 GFile *
 gtk_video_get_file (GtkVideo *self)
 {
@@ -664,11 +668,11 @@ gtk_video_get_file (GtkVideo *self)
 
 /**
  * gtk_video_set_file:
- * @self: a #GtkVideo
+ * @self: a `GtkVideo`
  * @file: (allow-none): the file to play
  *
  * Makes @self play the given @file.
- **/
+ */
 void
 gtk_video_set_file (GtkVideo *self,
                     GFile    *file)
@@ -711,13 +715,13 @@ gtk_video_set_file (GtkVideo *self,
 
 /**
  * gtk_video_set_filename:
- * @self: a #GtkVideo
+ * @self: a `GtkVideo`
  * @filename: (allow-none): the filename to play
  *
  * Makes @self play the given @filename.
  *
  * This is a utility function that calls gtk_video_set_file(),
- **/
+ */
 void
 gtk_video_set_filename (GtkVideo   *self,
                         const char *filename)
@@ -739,13 +743,13 @@ gtk_video_set_filename (GtkVideo   *self,
 
 /**
  * gtk_video_set_resource:
- * @self: a #GtkVideo
+ * @self: a `GtkVideo`
  * @resource_path: (allow-none): the resource to set
  *
  * Makes @self play the resource at the given @resource_path.
  *
- * This is a utility function that calls gtk_video_set_file(),
- **/
+ * This is a utility function that calls [method@Gtk.Video.set_file].
+ */
 void
 gtk_video_set_resource (GtkVideo   *self,
                         const char *resource_path)
@@ -779,12 +783,12 @@ gtk_video_set_resource (GtkVideo   *self,
 
 /**
  * gtk_video_get_autoplay:
- * @self: a #GtkVideo
+ * @self: a `GtkVideo`
  *
- * Returns %TRUE if videos have been set to loop via gtk_video_set_loop().
+ * Returns %TRUE if videos have been set to loop.
  *
  * Returns: %TRUE if streams should autoplay
- **/
+ */
 gboolean
 gtk_video_get_autoplay (GtkVideo *self)
 {
@@ -795,12 +799,12 @@ gtk_video_get_autoplay (GtkVideo *self)
 
 /**
  * gtk_video_set_autoplay:
- * @self: a #GtkVideo
+ * @self: a `GtkVideo`
  * @autoplay: whether media streams should autoplay
  *
- * Sets whether @self automatically starts playback when it becomes visible
- * or when a new file gets loaded.
- **/
+ * Sets whether @self automatically starts playback when it
+ * becomes visible or when a new file gets loaded.
+ */
 void
 gtk_video_set_autoplay (GtkVideo *self,
                         gboolean  autoplay)
@@ -817,12 +821,12 @@ gtk_video_set_autoplay (GtkVideo *self,
 
 /**
  * gtk_video_get_loop:
- * @self: a #GtkVideo
+ * @self: a `GtkVideo`
  *
- * Returns %TRUE if videos have been set to loop via gtk_video_set_loop().
+ * Returns %TRUE if videos have been set to loop.
  *
  * Returns: %TRUE if streams should loop
- **/
+ */
 gboolean
 gtk_video_get_loop (GtkVideo *self)
 {
@@ -833,11 +837,11 @@ gtk_video_get_loop (GtkVideo *self)
 
 /**
  * gtk_video_set_loop:
- * @self: a #GtkVideo
+ * @self: a `GtkVideo`
  * @loop: whether media streams should loop
  *
  * Sets whether new files loaded by @self should be set to loop.
- **/
+ */
 void
 gtk_video_set_loop (GtkVideo *self,
                     gboolean  loop)
@@ -851,4 +855,3 @@ gtk_video_set_loop (GtkVideo *self,
 
   g_object_notify_by_pspec (G_OBJECT (self), properties[PROP_LOOP]);
 }
-