[clutter] clutter-media: mention the asynchronous behavior of set_playing() in the doc.

[Emmanuele Bassi <ebassi src gnome org>]

commit 2544e878697f116b21b5aa88e2b4378dae807897
Author: Samuel Degrande <Samuel Degrande lifl fr>
Date:   Fri May 20 15:57:51 2011 +0200

    clutter-media: mention the asynchronous behavior of set_playing() in the doc.
    
    Depending on the ClutterMedia implementation, the set_playing()
    call can be asynchronous, the playing state's change being not
    immediate.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=650675

 clutter/clutter-media.c |    8 +++++++-
 1 files changed, 7 insertions(+), 1 deletions(-)
---
diff --git a/clutter/clutter-media.c b/clutter/clutter-media.c
index c05e39b..286d024 100644
--- a/clutter/clutter-media.c
+++ b/clutter/clutter-media.c
@@ -280,7 +280,13 @@ clutter_media_get_uri (ClutterMedia *media)
  * @media: a #ClutterMedia
  * @playing: %TRUE to start playing
  *
- * Starts or stops playing of @media.
+ * Starts or stops playing of @media. 
+ 
+ * The implementation might be asynchronous, so the way to know whether
+ * the actual playing state of the @media is to use the #GObject::notify
+ * signal on the #ClutterMedia:playing property and then retrieve the
+ * current state with clutter_media_get_playing(). ClutterGstVideoTexture
+ * in clutter-gst is an example of such an asynchronous implementation.
  *
  * Since: 0.2
  */