[gtk] Add more media docs

[Matthias Clasen <matthiasc src gnome org>]

commit 79e54929a2ae692973352ec17c731b2272849270
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun May 6 15:37:13 2018 -0400

    Add more media docs

 docs/reference/gtk/gtk4-sections.txt | 11 +++++
 gtk/gtkmediacontrols.c               |  8 ++++
 gtk/gtkmediafile.c                   |  6 ++-
 gtk/gtkmediastream.c                 | 84 +++++++++++++++++++++++++++++++++++-
 gtk/gtkvideo.c                       |  4 ++
 5 files changed, 110 insertions(+), 3 deletions(-)
---
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index c3caa92f48..7a7a593525 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -6875,6 +6875,17 @@ gtk_media_stream_set_volume
 gtk_media_stream_realize
 gtk_media_stream_unrealize
 
+<SUBSECTION>
+gtk_media_stream_prepared
+gtk_media_stream_unprepared
+gtk_media_stream_update
+gtk_media_stream_ended
+gtk_media_stream_seek_success
+gtk_media_stream_seek_failed
+gtk_media_stream_gerror
+gtk_media_stream_error
+gtk_media_stream_error_valist
+
 <SUBSECTION Private>
 GTK_TYPE_MEDIA_STREAM
 gtk_media_stream_get_type
diff --git a/gtk/gtkmediacontrols.c b/gtk/gtkmediacontrols.c
index 38a9bbbf23..22d1852b48 100644
--- a/gtk/gtkmediacontrols.c
+++ b/gtk/gtkmediacontrols.c
@@ -30,6 +30,7 @@
  * SECTION:gtkmediacontrols
  * @title: GtkMediaControls
  * @short_description: A widget showing controls for a media stream
+ * @see_also: #GtkVideo
  *
  * GtkMediaControls is a widget to show controls for a #GtkMediaStream
  * and giving users a way to use it.
@@ -464,6 +465,13 @@ gtk_media_controls_notify_cb (GtkMediaStream   *stream,
     update_volume (controls);
 }
 
+/**
+ * gtk_media_controls_set_media_stream:
+ * @controls: a #GtkMediaControls widget
+ * @stream: (nullable):  a #GtkMediaStream, or %NULL
+ *
+ * Sets the stream that is controlled by @controls.
+ */
 void
 gtk_media_controls_set_media_stream (GtkMediaControls *controls,
                                      GtkMediaStream   *stream)
diff --git a/gtk/gtkmediafile.c b/gtk/gtkmediafile.c
index 7c3f30f929..bc050eedfb 100644
--- a/gtk/gtkmediafile.c
+++ b/gtk/gtkmediafile.c
@@ -30,11 +30,15 @@
  * SECTION:gtkmediafile
  * @Short_description: Open media files for use in GTK
  * @Title: GtkMediaFile
- * @See_also: #GtkMediaStream
+ * @See_also: #GtkMediaStream, #GtkVideo
  *
  * #GtkMediaFile is the implementation for media file usage with #GtkMediaStream.
  *
  * This provides a simple way to play back video files with GTK.
+ *
+ * GTK+ provides a GIO extension point for #GtkMediaFile implementations
+ * to allow for external implementations using various media frameworks.
+ * GTK+ itself includes implementations using GStreamer and ffmpeg.
  */
 
 typedef struct _GtkMediaFilePrivate GtkMediaFilePrivate;
diff --git a/gtk/gtkmediastream.c b/gtk/gtkmediastream.c
index 9153c700c6..d36dde593e 100644
--- a/gtk/gtkmediastream.c
+++ b/gtk/gtkmediastream.c
@@ -31,8 +31,18 @@
  *
  * #GtkMediaStream is the integration point for media playback inside GTK.
  *
- * FIXME: Write more about how frameworks should implement this thing and how
- * GTK widgets exist (once they do) that consume it.
+ * Apart from application-facing API for stream playback, #GtkMediaStream
+ * has a number of APIs that are only useful for implementations and should
+ * not be used in applications:
+ * gtk_media_stream_prepared(),
+ * gtk_media_stream_unprepared(),
+ * gtk_media_stream_update(),
+ * gtk_media_stream_ended(),
+ * gtk_media_stream_seek_success(),
+ * gtk_media_stream_seek_failed(),
+ * gtk_media_stream_gerror(),
+ * gtk_media_stream_error(),
+ * gtk_media_stream_error_valist().
  */
 
 typedef struct _GtkMediaStreamPrivate GtkMediaStreamPrivate;
@@ -448,6 +458,15 @@ gtk_media_stream_init (GtkMediaStream *self)
   priv->volume = 1.0;
 }
 
+/**
+ * gtk_media_stream_is_prepared:
+ * @self: a #GtkMediaStream
+ *
+ * Returns whether the stream has finished initializing and existence of
+ * audio and video is known.
+ *
+ * Returns: %TRUE if the stream is prepared
+ */
 gboolean
 gtk_media_stream_is_prepared (GtkMediaStream *self)
 {
@@ -458,6 +477,14 @@ gtk_media_stream_is_prepared (GtkMediaStream *self)
   return priv->prepared;
 }
 
+/**
+ * gtk_media_stream_has_audio:
+ * @self: a #GtkMediaStream
+ *
+ * Returns whether the stream has audio.
+ *
+ * Returns: %TRUe if the stream has audio
+ */
 gboolean
 gtk_media_stream_has_audio (GtkMediaStream *self)
 {
@@ -468,6 +495,14 @@ gtk_media_stream_has_audio (GtkMediaStream *self)
   return priv->has_audio;
 }
 
+/**
+ * gtk_media_stream_has_video:
+ * @self: a #GtkMediaStream
+ *
+ * Returns whether the stream has video.
+ *
+ * Returns: %TRUe if the stream has video 
+ */
 gboolean
 gtk_media_stream_has_video (GtkMediaStream *self)
 {
@@ -478,6 +513,13 @@ gtk_media_stream_has_video (GtkMediaStream *self)
   return priv->has_video;
 }
 
+/**
+ * gtk_media_stream_play:
+ * @self: a #GtkMediaStream
+ *
+ * Starts playing the stream. If the stream
+ * is in error or already playing, do nothing.
+ */
 void
 gtk_media_stream_play (GtkMediaStream *self)
 {
@@ -508,6 +550,13 @@ gtk_media_stream_play (GtkMediaStream *self)
     }
 }
 
+/**
+ * gtk_media_stream_pause:
+ * @self: a #GtkMediaStream
+ *
+ * Pauses playback of the stream. If the stream
+ * is not playing, do nothing.
+ */
 void
 gtk_media_stream_pause (GtkMediaStream *self)
 {
@@ -527,6 +576,14 @@ gtk_media_stream_pause (GtkMediaStream *self)
   g_object_notify_by_pspec (G_OBJECT (self), properties[PROP_PLAYING]);
 }
 
+/**
+ * gtk_media_stream_get_playing:
+ * @self: a #GtkMediaStream
+ *
+ * Return whether the stream is currently playing.
+ *
+ * Returns: %TRUE if the stream is playing
+ */
 gboolean
 gtk_media_stream_get_playing (GtkMediaStream *self)
 {
@@ -537,6 +594,13 @@ gtk_media_stream_get_playing (GtkMediaStream *self)
   return priv->playing;
 }
 
+/**
+ * gtk_media_stream_set_playing:
+ * @self: a #GtkMediaStream
+ * @playing: whether to start or pause playback
+ *
+ * Starts or pauses playback of the stream.
+ */
 void
 gtk_media_stream_set_playing (GtkMediaStream *self,
                               gboolean        playing)
@@ -549,6 +613,14 @@ gtk_media_stream_set_playing (GtkMediaStream *self,
     gtk_media_stream_pause (self);
 }
 
+/**
+ * gtk_medai_stream_get_ended:
+ * @self: a #GtkMediaStream
+ *
+ * Returns whether the streams playback is finished.
+ *
+ * Return: %TRUE if playback is finished
+ */
 gboolean
 gtk_media_stream_get_ended (GtkMediaStream *self)
 {
@@ -559,6 +631,14 @@ gtk_media_stream_get_ended (GtkMediaStream *self)
   return priv->ended;
 }
 
+/**
+ * gtk_media_stream_get_timestamp:
+ * @self: a #GtkMediaStream
+ *
+ * Returns the current presentation timestamp in microseconds.
+ *
+ * Return: the timestamp in microseconds
+ */
 gint64
 gtk_media_stream_get_timestamp (GtkMediaStream *self)
 {
diff --git a/gtk/gtkvideo.c b/gtk/gtkvideo.c
index 8b12bf1f15..3756d03bac 100644
--- a/gtk/gtkvideo.c
+++ b/gtk/gtkvideo.c
@@ -32,8 +32,12 @@
  * SECTION:gtkvideo
  * @title: GtkVideo
  * @short_description: A widget for displaying video
+ * @see_also: #GtkMediaControls
  *
  * GtkVideo is a widget to show a #GtkMediaStream.
+ *
+ * It is commonly combined with #GtkMediaControls to give the
+ * user a way to control the playback.
  */
 
 struct _GtkVideo