diff --git a/gtk/gtkmediastream.c b/gtk/gtkmediastream.c
index c7c0a6fb0c..29c9c310a2 100644
--- a/gtk/gtkmediastream.c
+++ b/gtk/gtkmediastream.c
@@ -27,10 +27,13 @@
  * SECTION:gtkmediastream
  * @Short_description: Display media in GTK
  * @Title: GtkMediaStream
- * @See_also: #GdkPaintable
+ * @See_also: #GdkPaintable, #GtkMediaFile
  *
  * #GtkMediaStream is the integration point for media playback inside GTK.
  *
+ * GTK provides an implementation of the #GtkMediaStream interface that
+ * is called #GtkMediaFile.
+ *
  * 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:
diff --git a/gtk/gtkvideo.c b/gtk/gtkvideo.c
index 8258e25145..15a5e25a36 100644
--- a/gtk/gtkvideo.c
+++ b/gtk/gtkvideo.c
@@ -36,12 +36,19 @@
  * SECTION:gtkvideo
  * @title: GtkVideo
  * @short_description: A widget for displaying video
- * @see_also: #GtkMediaControls
+ * @see_also: #GtkMediaControls, #GtkMediaStream
  *
- * GtkVideo is a widget to show a #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.
  *
- * It is commonly combined with #GtkMediaControls to give the
- * user a way to control the playback.
+ * 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.
  */
 
 struct _GtkVideo