Add more media docs

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

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)

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;

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)
 {

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