[gtkmm] Device: Document some methods.

[Murray Cumming <murrayc src gnome org>]

commit 7ccf4667aeb1a76d9f766d63a171ade231491674
Author: Murray Cumming <murrayc murrayc com>
Date:   Wed Oct 9 10:02:12 2013 +0200

    Device: Document some methods.

 gdk/src/device.hg |   37 +++++++++++++++++++++++++++++++++----
 1 files changed, 33 insertions(+), 4 deletions(-)
---
diff --git a/gdk/src/device.hg b/gdk/src/device.hg
index 63ac5d7..ca6c871 100644
--- a/gdk/src/device.hg
+++ b/gdk/src/device.hg
@@ -65,7 +65,17 @@ public:
   _WRAP_METHOD(void set_axis_use(guint index_, AxisUse use), gdk_device_set_axis_use)
   _WRAP_METHOD(void get_state(const Glib::RefPtr<Window>& window, double& axes, ModifierType& mask), 
gdk_device_get_state)
 
-  // TODO: docs.
+  /** Obtains the motion history for a device.
+   * Given a starting and ending timestamp, this will return all events
+   * in the motion history for the device in the given range of time.
+   * Some windowing systems do not support motion history, in which case, false will be returned.
+   * (This is not distinguishable from the case where motion history is supported and no events were found.)
+   *
+   * @param window The window with respect to which which the event coordinates will be reported.
+   * @param start Starting timestamp for range of events to return.
+   * @param stop Ending timestamp for the range of events to return.
+   * @result A vector of TimeCoord.
+   */
   std::vector<TimeCoord> get_history(const Glib::RefPtr<Window>& window, guint32 start, guint32 stop) const;
   _IGNORE(gdk_device_get_history)
 
@@ -96,7 +106,8 @@ public:
 
   _WRAP_METHOD(GrabStatus grab(const Glib::RefPtr<Window>& window, GrabOwnership grab_ownership, bool 
owner_events, EventMask event_mask, const Glib::RefPtr<Cursor>& cursor, guint32 time_), gdk_device_grab)
 
-  // TODO: docs.
+  /** See the grab() method which takes more parameters.
+   */
   GrabStatus grab(const Glib::RefPtr<Window>& window, GrabOwnership grab_ownership, bool owner_events, 
EventMask event_mask, guint32 time_);
 
   _WRAP_METHOD(void ungrab(guint32 time_), gdk_device_ungrab)
@@ -155,10 +166,28 @@ public:
 
   _WRAP_METHOD(Glib::RefPtr<const Window> get_window_at_position(int& win_x, int& win_y) const, 
gdk_device_get_window_at_position, refreturn, constversion)
 
-  //TODO: Documentation
+  /** Obtains the window underneath the device.
+   * Returns an empty RefPtr if the window tree under the device is not known to GDK (for example, belongs 
to another application).
+   * 
+   * As a slave device coordinates are those of its master pointer, This
+   * function may not be called on devices of type Gdk::DEVICE_TYPE_SLAVE,
+   * unless there is an ongoing grab on them. See grab().
+   * 
+   * @newin{3,0}
+   * @return The Gdk::Window under the device position.
+   */
   Glib::RefPtr<Window> get_window_at_position();
 
-  //TODO: Documentation
+  /** Obtains the window underneath the device.
+   * Returns an empty RefPtr if the window tree under the device is not known to GDK (for example, belongs 
to another application).
+   * 
+   * As a slave device coordinates are those of its master pointer, This
+   * function may not be called on devices of type Gdk::DEVICE_TYPE_SLAVE,
+   * unless there is an ongoing grab on them. See grab().
+   * 
+   * @newin{3,0}
+   * @return The Gdk::Window under the device position.
+   */
   Glib::RefPtr<const Window> get_window_at_position() const;
 
 };