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

[Matthias Clasen <matthiasc src gnome org>]

commit b1bb4e1eca4f7c2000180acdf9a012454c680ae3
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 GtkMediaStream,
    and mention that GtkPicture can display video just fine.

 gtk/gtkmediastream.c | 7 +++++++
 gtk/gtkvideo.c       | 7 +++----
 2 files changed, 10 insertions(+), 4 deletions(-)
---
diff --git a/gtk/gtkmediastream.c b/gtk/gtkmediastream.c
index c7c0a6fb0c..5275ea1a1c 100644
--- a/gtk/gtkmediastream.c
+++ b/gtk/gtkmediastream.c
@@ -31,6 +31,13 @@
  *
  * #GtkMediaStream is the integration point for media playback inside GTK.
  *
+ * GtkMediaStream 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, 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.
+ *
  * 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..51f7a64c3e 100644
--- a/gtk/gtkvideo.c
+++ b/gtk/gtkvideo.c
@@ -38,10 +38,9 @@
  * @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.
+ * 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 use #GtkPicture.
  */
 
 struct _GtkVideo