[PATCH libinput 08/26] tablet: document what the tool type means

[Peter Hutterer]

On Tue, Feb 24, 2015 at 11:47:26AM -0500, Benjamin Tissoires wrote:
> On Tue, Feb 24, 2015 at 1:21 AM, Peter Hutterer
> <peter.hutterer at who-t.net> wrote:
> > It's a rough guide only, but still precise enough to make some decisions.
> >
> > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> > ---
> >  src/libinput.h | 32 +++++++++++++++++++++++---------
> >  1 file changed, 23 insertions(+), 9 deletions(-)
> >
> > diff --git a/src/libinput.h b/src/libinput.h
> > index f5c4e9f..984e8e3 100644
> > --- a/src/libinput.h
> > +++ b/src/libinput.h
> > @@ -156,17 +156,31 @@ struct libinput_tool;
> >   * @ingroup device
> >   *
> >   * Available tool types for a device. It must have the @ref
> > - * LIBINPUT_DEVICE_CAP_TABLET capability.
> > + * 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,
> > + * Wacom Pro Pen and a Wacom Grip Pen are all of type LIBINPUT_TOOL_PEN.
> > + * Use libinput_tool_get_tool_id() to get a specific model where applicable.
> 
> We might need to @ref libinput_tool_get_tool_id()

not needed, doxygen is smart enough to ref functions with () appended. So
you can either write @ref foo or foo(), both resolve correctly.
 
> And BTW, libinput_tool_get_tool_id() is added in the next commit :)

oops, rebase detritus. moved that sentence to the tool_id patch.

Cheers,
   Peter

> > + *
> > + * Note that on some device, the eraser tool is on the tail end of a pen
> > + * device. On other devices, e.g. MS Surface 3, the eraser is the pen tip
> > + * while a button is held down.
> > + *
> > + * @note The @ref libinput_tool_type can only describe the default physical
> > + * type of the device. For devices with adjustible physical properties
> > + * the tool type remains the same, i.e. putting a Wacom stroke nib into a
> > + * classic pen leaves the tool type as @ref LIBINPUT_TOOL_PEN.
> >   */
> >  enum libinput_tool_type {
> > -       LIBINPUT_TOOL_PEN = 1,
> > -       LIBINPUT_TOOL_ERASER,
> > -       LIBINPUT_TOOL_BRUSH,
> > -       LIBINPUT_TOOL_PENCIL,
> > -       LIBINPUT_TOOL_AIRBRUSH,
> > -       LIBINPUT_TOOL_FINGER,
> > -       LIBINPUT_TOOL_MOUSE,
> > -       LIBINPUT_TOOL_LENS
> > +       LIBINPUT_TOOL_PEN = 1,          /**< A generic pen */
> > +       LIBINPUT_TOOL_ERASER,           /**< Eraser */
> > +       LIBINPUT_TOOL_BRUSH,            /**< A paintbrush-like tool */
> > +       LIBINPUT_TOOL_PENCIL,           /**< Physical drawing tool, e.g.
> > +                                            Wacom Inking Pen */
> > +       LIBINPUT_TOOL_AIRBRUSH,         /**< An airbrush-like tool */
> > +       LIBINPUT_TOOL_FINGER,           /**< Touch */
> > +       LIBINPUT_TOOL_MOUSE,            /**< A mouse bound to the tablet */
> > +       LIBINPUT_TOOL_LENS,             /**< A mouse tool with a lens */
> >  };
> >
> >  /**
> > --
> > 2.1.0
> >
> > _______________________________________________
> > wayland-devel mailing list
> > wayland-devel at lists.freedesktop.org
> > http://lists.freedesktop.org/mailman/listinfo/wayland-devel