[clutter] ClutterEvent: Mention _get_source_device() in docs

[Bastien Nocera <hadess src gnome org>]

commit 79c2d3ede7a2e379bf110bacee92932de9793aff
Author: Bastien Nocera <hadess hadess net>
Date:   Tue Oct 8 11:40:23 2013 +0200

    ClutterEvent: Mention _get_source_device() in docs
    
    It's too easy getting bitten by the ->device red herring, thinking
    that it's the original input device the event originated from.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=709620

 clutter/clutter-event.c |    2 ++
 clutter/clutter-event.h |   18 ++++++++++++------
 2 files changed, 14 insertions(+), 6 deletions(-)
---
diff --git a/clutter/clutter-event.c b/clutter/clutter-event.c
index 7fdbf83..542a83f 100644
--- a/clutter/clutter-event.c
+++ b/clutter/clutter-event.c
@@ -1015,6 +1015,8 @@ clutter_event_set_device (ClutterEvent       *event,
  * @event: a #ClutterEvent
  *
  * Retrieves the #ClutterInputDevice for the event.
+ * If you want the physical device the event originated from, use
+ * clutter_event_get_source_device().
  *
  * The #ClutterInputDevice structure is completely opaque and should
  * be cast to the platform-specific implementation.
diff --git a/clutter/clutter-event.h b/clutter/clutter-event.h
index 23781cc..17c4279 100644
--- a/clutter/clutter-event.h
+++ b/clutter/clutter-event.h
@@ -146,7 +146,8 @@ struct _ClutterAnyEvent
  * @keyval: raw key value
  * @hardware_keycode: raw hardware key value
  * @unicode_value: Unicode representation
- * @device: reserved for future use
+ * @device: the device that originated the event. If you want the physical
+ * device the event originated from, use clutter_event_get_source_device()
  *
  * Key event
  *
@@ -181,7 +182,8 @@ struct _ClutterKeyEvent
  * @click_count: number of button presses within the default time
  *   and radius
  * @axes: reserved for future use
- * @device: reserved for future use
+ * @device: the device that originated the event. If you want the physical
+ * device the event originated from, use clutter_event_get_source_device()
  *
  * Button event.
  *
@@ -218,7 +220,8 @@ struct _ClutterButtonEvent
  * @x: event X coordinate
  * @y: event Y coordinate
  * @related: actor related to the crossing
- * @device: reserved for future use
+ * @device: the device that originated the event. If you want the physical
+ * device the event originated from, use clutter_event_get_source_device()
  *
  * Event for the movement of the pointer across different actors
  *
@@ -249,7 +252,8 @@ struct _ClutterCrossingEvent
  * @y: event Y coordinate
  * @modifier_state: button modifiers
  * @axes: reserved for future use
- * @device: reserved for future use
+ * @device: the device that originated the event. If you want the physical
+ * device the event originated from, use clutter_event_get_source_device()
  *
  * Event for the pointer motion
  *
@@ -282,7 +286,8 @@ struct _ClutterMotionEvent
  * @direction: direction of the scrolling
  * @modifier_state: button modifiers
  * @axes: reserved for future use
- * @device: reserved for future use
+ * @device: the device that originated the event. If you want the physical
+ * device the event originated from, use clutter_event_get_source_device()
  *
  * Scroll wheel (or similar device) event
  *
@@ -344,7 +349,8 @@ struct _ClutterStageStateEvent
  *   of modifier keys (e.g. Control, Shift, and Alt) and the pointer
  *   buttons. See #ClutterModifierType
  * @axes: reserved 
- * @device: the device that originated the event
+ * @device: the device that originated the event. If you want the physical
+ * device the event originated from, use clutter_event_get_source_device()
  *
  * Used for touch events.
  *