[gtk/matthiasc/for-master] video: Tweak the docs

[Matthias Clasen <matthiasc src gnome org>]

commit c8046453828405cfaf6e103703d36274aad0f116
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Jan 2 11:17:26 2021 -0500

    video: Tweak the docs
    
    Point out the limitations and use cases of GtkVideo
    and mention that GtkPicture can display video just fine.

 gtk/gtkmediastream.c |  5 ++++-
 gtk/gtkvideo.c       | 19 +++++++++++++------
 2 files changed, 17 insertions(+), 7 deletions(-)
---
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
- *
- * GtkVideo is a widget to show a #GtkMediaStream.
- *
- * It is commonly combined with #GtkMediaControls to give the
- * user a way to control the playback.
+ * @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 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