gstplay: Add a minimal documentation header

Also mentioning the need to set the bus to flushing state before disposing the
player in order to avoid reference cycles.

Fixes #3107

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/5631>

girs/GstPlay-1.0.gir

@@ -306,6 +306,33 @@ and/or use gtk-doc annotations.  -->
       </parameters>
     </function-macro>
     <class name="Play" c:symbol-prefix="play" c:type="GstPlay" version="1.20" parent="Gst.Object" glib:type-name="GstPlay" glib:get-type="gst_play_get_type" glib:type-struct="PlayClass">
+      <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">The goal of the GstPlay library is to ease the integration of multimedia
+playback features in applications. Thus, if you need to build a media player
+from the ground-up, GstPlay provides the features you will most likely need.
+
+An example player is available in gst-examples/playback/player/gst-play/.
+
+Internally the GstPlay makes use of the `playbin` element. `playbin3` can be
+selected if the `GST_PLAY_USE_PLAYBIN3=1` environment variable has been set.
+
+**Important note**: In order to prevent the GstPlay object from leaking, its
+GstBus should be set to flushing state before any attempt to drop the last
+reference of the GstPlay object. An example in C:
+
+```c
+...
+GstBus *bus = gst_play_get_message_bus (player);
+gst_bus_set_flushing (bus, TRUE);
+gst_object_unref (bus);
+gst_object_unref (player);
+```
+
+The messages managed by the player contain a reference to itself, and if the
+bus watch is just removed together with dropping the player then the bus will
+simply keep them around forever (and the bus never goes away because the
+player has a strong reference to it, so there's a reference cycle as long as
+there are messages). Setting the bus to flushing state forces it to get rid
+of its queued messages, thus breaking any possible reference cycle.</doc>
       <source-position filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay-types.h"/>
       <constructor name="new" c:identifier="gst_play_new" version="1.20">
         <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">Creates a new #GstPlay instance.

subprojects/gst-examples/playback/player/gst-play/gst-play.c

@@ -390,8 +390,14 @@ play_new (gchar ** uris, gdouble initial_volume)
 static void
 play_free (Player * play)
 {
+  GstBus *bus = NULL;
+
   play_reset (play);
 
+  bus = gst_play_get_message_bus (play->player);
+  gst_bus_set_flushing (bus, TRUE);
+  gst_object_unref (bus);
+
   g_clear_object (&play->signal_adapter);
   gst_object_unref (play->player);
 

subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c

@@ -28,6 +28,34 @@
  * @symbols:
  * - GstPlay
  *
+ * The goal of the GstPlay library is to ease the integration of multimedia
+ * playback features in applications. Thus, if you need to build a media player
+ * from the ground-up, GstPlay provides the features you will most likely need.
+ *
+ * An example player is available in gst-examples/playback/player/gst-play/.
+ *
+ * Internally the GstPlay makes use of the `playbin` element. `playbin3` can be
+ * selected if the `GST_PLAY_USE_PLAYBIN3=1` environment variable has been set.
+ *
+ * **Important note**: In order to prevent the GstPlay object from leaking, its
+ * GstBus should be set to flushing state before any attempt to drop the last
+ * reference of the GstPlay object. An example in C:
+ *
+ * ```c
+ * ...
+ * GstBus *bus = gst_play_get_message_bus (player);
+ * gst_bus_set_flushing (bus, TRUE);
+ * gst_object_unref (bus);
+ * gst_object_unref (player);
+ * ```
+ *
+ * The messages managed by the player contain a reference to itself, and if the
+ * bus watch is just removed together with dropping the player then the bus will
+ * simply keep them around forever (and the bus never goes away because the
+ * player has a strong reference to it, so there's a reference cycle as long as
+ * there are messages). Setting the bus to flushing state forces it to get rid
+ * of its queued messages, thus breaking any possible reference cycle.
+ *
  * Since: 1.20
  */