[mutter] clutter: Clarify clutter_stage_get_actor_at_pos docs

[Marco Trevisan <marcotrevi src gnome org>]

commit 9db9793f336c66ceb40c7a46d0cff21d9c6ec010
Author: Daniel van Vugt <daniel van vugt canonical com>
Date:   Fri Aug 31 15:11:54 2018 +0800

    clutter: Clarify clutter_stage_get_actor_at_pos docs
    
    When a user moves their cursor the perceived behaviour is that it will
    pick what is under the cursor. However this isn't how picking works.
    Picking does a virtual redraw of the screen, so in some cases what gets
    picked isn't the same as what the user could see on the previous frame.
    It more represents what will be drawn on the next frame than what is on
    screen at present.
    
    It may be unsafe to change these semantics, and they are useful anyway.
    Just document it better.
    
    https://gitlab.gnome.org/GNOME/mutter/merge_requests/214

 clutter/clutter/clutter-stage.c | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)
---
diff --git a/clutter/clutter/clutter-stage.c b/clutter/clutter/clutter-stage.c
index 0975f2f90..f5189c5c8 100644
--- a/clutter/clutter/clutter-stage.c
+++ b/clutter/clutter/clutter-stage.c
@@ -3031,7 +3031,11 @@ clutter_stage_read_pixels (ClutterStage *stage,
  * @y: Y coordinate to check
  *
  * Checks the scene at the coordinates @x and @y and returns a pointer
- * to the #ClutterActor at those coordinates.
+ * to the #ClutterActor at those coordinates. The result is the actor which
+ * would be at the specified location on the next redraw, and is not
+ * necessarily that which was there on the previous redraw. This allows the
+ * function to perform chronologically correctly after any queued changes to
+ * the scene, and even if nothing has been drawn.
  *
  * By using @pick_mode it is possible to control which actors will be
  * painted and thus available.