diff --git a/src/libinput.h b/src/libinput.h
index bb24c959..9a377f8b 100644
--- a/src/libinput.h
+++ b/src/libinput.h
@@ -155,15 +155,20 @@ enum libinput_tablet_axis {
 /**
  * @ingroup device
  *
- * An object representing a tool being used by the device. It must have the @ref
+ * An object representing a tool being used by a device with the @ref
  * LIBINPUT_DEVICE_CAP_TABLET capability.
+ *
+ * Tablet events generated by such a device are bound to a specific tool
+ * rather than coming from the device directly. Depending on the hardware it
+ * is possible to track the same physical tool across multiple
+ * struct libinput_device devices.
  */
 struct libinput_tool;
 
 /**
  * @ingroup device
  *
- * Available tool types for a device. It must have the @ref
+ * Available tool types for a device with the @ref
  * LIBINPUT_DEVICE_CAP_TABLET capability. The tool type defines the default
  * usage of the tool as advertised by the manufacturer. Multiple different
  * physical tools may share the same tool type, e.g. a Wacom Classic Pen,
@@ -196,6 +201,14 @@ enum libinput_tool_type {
  *
  * The state of proximity for a tool on a device. The device must have the @ref
  * LIBINPUT_DEVICE_CAP_TABLET capability.
+ *
+ * The proximity of a tool is a binary state signalling whether the tool is
+ * within detectable distance of the tablet device. A tool that is out of
+ * proximity cannot generate events.
+ *
+ * On some hardware a tool goes out of proximity when it ceases to touch the
+ * surface. On other hardware, the tool is still detectable within a short
+ * distance (a few cm) off the surface.
  */
 enum libinput_tool_proximity_state {
 	LIBINPUT_TOOL_PROXIMITY_OUT = 0,
@@ -248,6 +261,12 @@ enum libinput_event_type {
 	 */
 	LIBINPUT_EVENT_TOUCH_FRAME,
 
+	/**
+	 * One or more axes have changed state on a device with the @ref
+	 * LIBINPUT_DEVICE_CAP_TABLET capability. This event is only sent
+	 * when the tool is in proximity, see @ref
+	 * LIBINPUT_EVENT_TABLET_PROXIMITY for details.
+	 */
 	LIBINPUT_EVENT_TABLET_AXIS = 600,
 	/**
 	 * Signals that a tool has come in or out of proximity of a device with
@@ -257,9 +276,9 @@ enum libinput_event_type {
 	 * and these values may be extracted from them in the same way they are
 	 * with @ref LIBINPUT_EVENT_TABLET_AXIS events.
 	 *
-	 * Some tools may always be in proximity. For these tools, events with
-	 * state @ref LIBINPUT_TOOL_PROXIMITY_IN are sent only once after @ref
-	 * LIBINPUT_EVENT_DEVICE_ADDED, and likewise events with state @ref
+	 * Some tools may always be in proximity. For these tools, events of
+	 * type @ref LIBINPUT_TOOL_PROXIMITY_IN are sent only once after @ref
+	 * LIBINPUT_EVENT_DEVICE_ADDED, and events of type @ref
 	 * LIBINPUT_TOOL_PROXIMITY_OUT are sent only once before @ref
 	 * LIBINPUT_EVENT_DEVICE_REMOVED.
 	 *
@@ -268,10 +287,10 @@ enum libinput_event_type {
 	 * event.
 	 *
 	 * When a tool goes out of proximity, the value of every axis should be
-	 * assumed to have a value of 0 and any buttons that are currently held
+	 * assumed to have an undefined state and any buttons that are currently held
 	 * down on the stylus are marked as released. Button release events for
 	 * each button that was held down on the stylus are sent before the
-	 * initial proximity out event.
+	 * proximity out event.
 	 */
 	LIBINPUT_EVENT_TABLET_PROXIMITY,
 	LIBINPUT_EVENT_TABLET_BUTTON,
@@ -1292,7 +1311,7 @@ libinput_event_tablet_axis_has_changed(struct libinput_event_tablet *event,
  *   Y coordinates of the tablet tool, in mm from the top left corner of the
  *   tablet. Use libinput_event_tablet_get_x_transformed() and
  *   libinput_event_tablet_get_y_transformed() for transforming each
- *   respective axis value.
+ *   respective axis value into a different coordinate space.
  * - @ref LIBINPUT_TABLET_AXIS_DISTANCE - The distance from the tablet's
  *   sensor, normalized from 0 to 1
  * - @ref LIBINPUT_TABLET_AXIS_PRESSURE - The current pressure being applied on
@@ -1316,6 +1335,10 @@ libinput_event_tablet_axis_has_changed(struct libinput_event_tablet *event,
  * libinput_event_tablet_axis_has_changed() returns 0 for that axis.
  * libinput always includes all device axes in the event.
  *
+ * If the event is of type @ref LIBINPUT_EVENT_TABLET_PROXIMITY and the
+ * event is a proximity out event, the value returned is the last known
+ * value of the tool before it left proximity.
+ *
  * @param event The libinput tablet event
  * @param axis The axis to retrieve the value of
  * @return The current value of the the axis