doc: copy some bits of the tablet docs to doxygen

So it shows up in the doxygen contents. These are the bits that are mostly of
interest to developers, we might remove the user documentation entry later,
but let's leave it there for now.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

diff --git a/src/libinput.h b/src/libinput.h
index 828cf6b..3413eeb 100644 (file)
--- a/src/libinput.h
+++ b/src/libinput.h
@@ -85,7 +85,8 @@ struct libinput_seat;
  * 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, see @ref tablet-serial-numbers.
+ * struct libinput_device devices.
+ * See libinput_tablet_tool_get_serial() for more details.
  *
  * This struct is refcounted, use libinput_tablet_tool_ref() and
  * libinput_tablet_tool_unref().
@@ -2255,8 +2256,8 @@ libinput_event_tablet_tool_get_y_transformed(struct libinput_event_tablet_tool *
  * whenever the tools enters proximity again.
   *
  * @note Physical tool tracking requires hardware support. If unavailable,
- * libinput creates one tool per type per tablet. See @ref
- * tablet-serial-numbers for more details.
+ * libinput creates one tool per type per tablet. See
+ * libinput_tablet_tool_get_serial() for more details.
  *
  * @param event The libinput tablet tool event
  * @return The new tool triggering this event
@@ -2271,7 +2272,19 @@ libinput_event_tablet_tool_get_tool(struct libinput_event_tablet_tool *event);
  * Used to check whether or not a tool came in or out of proximity during an
  * event of type @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY.
  *
- * See @ref tablet-fake-proximity for recommendations on proximity handling.
+ * The proximity state represents the logical proximity state which does not
+ * necessarily match when a tool comes into sensor range or leaves the
+ * sensor range. On some tools this range does not represent the physical
+ * range but a reduced tool-specific logical range. If the range is reduced,
+ * this is done transparent to the caller.
+ *
+ * For example, the Wacom mouse and lens cursor tools are usually
+ * used in relative mode, lying flat on the tablet. Movement typically follows
+ * the interaction normal mouse movements have, i.e. slightly lift the tool and
+ * place it in a separate location. The proximity detection on Wacom
+ * tablets however extends further than the user may lift the mouse, i.e. the
+ * tool may not be lifted out of physical proximity. For such tools, libinput
+ * provides software-emulated proximity.
  *
  * @param event The libinput tablet tool event
  * @return The new proximity state of the tool from the event.
@@ -2365,8 +2378,18 @@ libinput_event_tablet_tool_get_time_usec(struct libinput_event_tablet_tool *even
 /**
  * @ingroup event_tablet
  *
- * Return the tool type for a tool object, see @ref
- * tablet-tool-types for details.
+ * Return the high-level tool type for a tool object.
+ *
+ * The high level tool describes general interaction expected with the tool.
+ * For example, a user would expect a tool of type @ref
+ * LIBINPUT_TABLET_TOOL_TYPE_PEN to interact with a graphics application
+ * taking pressure and tilt into account. The default virtual tool assigned
+ * should be a drawing tool, e.g. a virtual pen or brush.
+ * A tool of type @ref LIBINPUT_TABLET_TOOL_TYPE_ERASER would normally be
+ * mapped to an eraser-like virtual tool.
+ *
+ * If supported by the hardware, a more specific tool id is always
+ * available, see * libinput_tablet_tool_get_tool_id().
  *
  * @param tool The libinput tool
  * @return The tool type for this tool object
@@ -2381,11 +2404,12 @@ libinput_tablet_tool_get_type(struct libinput_tablet_tool *tool);
  *
  * Return the tool ID for a tool object. If nonzero, this number identifies
  * the specific type of the tool with more precision than the type returned in
- * libinput_tablet_tool_get_type(), see @ref tablet-tool-types. Not all
- * tablets support a tool ID.
+ * libinput_tablet_tool_get_type(). Not all tablets support a tool ID.
  *
  * Tablets known to support tool IDs include the Wacom Intuos 3, 4, 5, Wacom
- * Cintiq and Wacom Intuos Pro series.
+ * Cintiq and Wacom Intuos Pro series. The tool ID can be used to
+ * distinguish between e.g. a Wacom Classic Pen or a Wacom Pro Pen.  It is
+ * the caller's responsibility to interpret the tool ID.
  *
  * @param tool The libinput tool
  * @return The tool ID for this tool object or 0 if none is provided
@@ -2512,7 +2536,7 @@ libinput_tablet_tool_has_button(struct libinput_tablet_tool *tool,
  * libinput, or nonzero otherwise. If a tool can be uniquely identified,
  * keeping a reference to the tool allows tracking the tool across
  * proximity out sequences and across compatible tablets.
- * See @ref tablet-serial-numbers for more details.
+ * See libinput_tablet_tool_get_serial() for more details.
  *
  * @param tool A tablet tool
  * @return 1 if the tool can be uniquely identified, 0 otherwise.
@@ -2526,8 +2550,30 @@ libinput_tablet_tool_is_unique(struct libinput_tablet_tool *tool);
  * @ingroup event_tablet
  *
  * Return the serial number of a tool. If the tool does not report a serial
- * number, this function returns zero. See @ref tablet-serial-numbers for
- * details.
+ * number, this function returns zero.
+ *
+ * Some tools provide hardware information that enables libinput to uniquely
+ * identify the physical device. For example, tools compatible with the
+ * Wacom Intuos 4, Intuos 5, Intuos Pro and Cintiq series are uniquely
+ * identifiable through a serial number. libinput does not specify how a
+ * tool can be identified uniquely, a caller should use
+ * libinput_tablet_tool_is_unique() to check if the tool is unique.
+ *
+ * libinput creates a struct @ref libinput_tablet_tool on the first
+ * proximity in of this tool. By default, this struct is destroyed on
+ * proximity out and re-initialized on the next proximity in. If a caller
+ * keeps a reference to the tool by using libinput_tablet_tool_ref()
+ * libinput re-uses this struct whenever that same physical tool comes into
+ * proximity on any tablet
+ * recognized by libinput. It is possible to attach tool-specific virtual
+ * state to the tool. For example, a graphics program such as the GIMP may
+ * assign a specific color to each tool, allowing the artist to use the
+ * tools like physical pens of different color. In multi-tablet setups it is
+ * also possible to track the tool across devices.
+ *
+ * If the tool does not have a unique identifier, libinput creates a single
+ * struct @ref libinput_tablet_tool per tool type on each tablet the tool is
+ * used on.
  *
  * @param tool The libinput tool
  * @return The tool serial number