doc: document the device quirks

Add some documentation for the most common quirks or at least the ones that
the user may eventually see or have to set. Drop the git commit hash into the
docs to make sure it's spelled out that the quirks are only valid for that
commit. Adding something with @include* requires the EXAMPLE_PATH to be set.

Doxygen doesn't parse markdown in @includedoc so we have to insert the commit
as normal HTML tag.

Related to https://gitlab.freedesktop.org/libinput/libinput/issues/87

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

4 files changed, 92 insertions, 2 deletions

diff --git a/doc/device-quirks.dox b/doc/device-quirks.dox
index 8bb5ec2b..d66a3a85 100644
--- a/doc/device-quirks.dox
+++ b/doc/device-quirks.dox
@@ -101,4 +101,86 @@ Note that this is an example only, the output may change over time. The tool
 uses the same parser as libinput and any parsing errors will show up in the
 output.
 
+@section device-quirks-list List of supported device quirks
+
+This list is a guide for developers to ease the process of submitting
+patches upstream. This section shows device quirks supported in git
+commit @includedoc git-version.dox
+
+@note <b>Quirks are internal API and may change at any time for any reason.
+No guarantee is given that any quirk below works on your version of
+libinput.</b>
+
+In the documentation below, the letters N, M, O, P refer to arbitrary integer
+values.
+
+Quirks starting with <b>Model*</b> triggers implementation-defined behaviour
+for this device not needed for any other device. Only the more
+general-purpose <b>Model*</b> flags are listed here.
+
+<dl>
+  <dt>ModelALPSTouchpad</dt>
+  <dt>ModelAppleTouchpad</dt>
+  <dt>ModelWacomTouchpad</dt>
+  <dt>ModelChromebook</dt>
+    <dd>Reserved for touchpads made by the respective vendors</dd>
+  <dt>ModelTabletNoTilt</dt>
+    <dd>Indicates that the tablet stylus does not provide tilt axis
+    information, even if the kernel exposes that axis.</dd>
+  <dt>ModelTabletNoProximityOut</dt>
+    <dd>Indicates that the tablet stylus does not send correct proximity out
+    events.</dd>
+  <dt>ModelTouchpadVisibleMarker</dt>
+    <dd>Indicates the touchpad has a drawn-on visible marker between the software
+    buttons.</dd>
+  <dt>ModelTabletModeNoSuspend</dt>
+    <dd>Indicates that the device does not need to be
+    suspended in @ref switches_tablet_mode.</dd>
+  <dt>ModelTrackball</dt>
+    <dd>Reserved for trackballs</dd>
+  <dt>ModelBouncingKeys</dt>
+    <dd>Indicates that the device may send fake bouncing key events and
+    timestamps can not be relied upon.</dd>
+  <dt>ModelSynapticsSerialTouchpad</dt>
+    <dd>Reserved for touchpads made by Synaptics on the serial bus</dd>
+  </dd>
+  <dt>AttrSizeHint=NxM</dt>
+  <dt>AttrResolutionHint=N</dt>
+    <dd>Hints at the width x height of the device in mm, or the resolution
+    of the x/y axis in units/mm. These may only be used where they apply to
+    a large proportion of matching devices. They should not be used for any
+    specific device, override `EVDEV_ABS_*` instead, see @ref
+    absolute_coordinate_ranges_fix.
+    </dd>
+  <dt>AttrTouchSizeRange=N:M</dt>
+  <dt>AttrPalmSizeThreshold=O</dt>
+    <dd>Specifies the touch size required to
+    trigger a press (N) and to trigger a release (M). O > N > M. See
+    @ref touchpad_touch_size_hwdb for more details.
+    </dd>
+  <dt>AttrTouchPressureRange=N:M</dt>
+  <dt>AttrPalmPressureThreshold=O</dt>
+  <dt>AttrThumbPressureThreshold=P</dt>
+    <dd>Specifies the touch pressure required to
+    trigger a press (N) and to trigger a release (M), when a palm touch is
+    triggered (O) and when a thumb touch is triggered (P). O > P > N > M. See
+    @ref touchpad_pressure_hwdb for more details.
+    </dd>
+  <dt>AttrLidSwitchReliability=reliable|write_open</dt>
+    <dd>
+    Indicates the reliability of the lid switch. This is a string enum. Do not
+    use "reliable" for any specific device. Very few devices need this, if in
+    doubt do not set. See @ref switches_lid for details.
+    </dd>
+  <dt>AttrKeyboardIntegration=internal|external</dt>
+    <dd>Indicates the integration of the keyboard. This is a string enum.
+    Generally only needed for USB keyboards.
+    </dd>
+  <dt>AttrTPKComboLayout=below</dt>
+    <dd>Indicates the position of the touchpad on an external touchpad+keyboard
+    combination device. This is a string enum. Don't specify it unless the
+    touchpad is below.
+    </dd>
+</dl>
+
 */
diff --git a/doc/git-version.dox b/doc/git-version.dox
new file mode 100644
index 00000000..d83ce069
--- /dev/null
+++ b/doc/git-version.dox
@@ -0,0 +1 @@
+<a href="https://gitlab.freedesktop.org/libinput/libinput/commit/__GIT_VERSION__">__GIT_VERSION__</a>
diff --git a/doc/libinput.doxygen.in b/doc/libinput.doxygen.in
index c2c664a1..713c661d 100644
--- a/doc/libinput.doxygen.in
+++ b/doc/libinput.doxygen.in
@@ -22,6 +22,7 @@ EXPAND_ONLY_PREDEF     = YES
 PREDEFINED             = LIBINPUT_ATTRIBUTE_PRINTF(f, a)= \
                          LIBINPUT_ATTRIBUTE_DEPRECATED
 DOTFILE_DIRS           = "@builddir@"
+EXAMPLE_PATH           = "@builddir@"
 
 HTML_HEADER = "@builddir@/header.html"
 HTML_FOOTER = "@builddir@/footer.html"
diff --git a/doc/meson.build b/doc/meson.build
index a42a2e0d..af4ffc76 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -29,6 +29,12 @@ if dot_version.version_compare('< 2.26')
 	error('Graphviz dot needs to be at least version 2.26 (have @0@)'.format(dot_version))
 endif
 
+doc_git_version = vcs_tag(command : ['git', 'log', '-1', '--format=%h'],
+			  fallback : 'ERROR - unable to fetch git version',
+			  input : 'git-version.dox',
+			  output : 'git-version.dox',
+			  replace_string: '__GIT_VERSION__')
+
 readme = vcs_tag(command : ['git', 'log', '-1', '--format=%h'],
 		 fallback : 'unknown',
 		 input : '../README.md',
@@ -132,9 +138,9 @@ doxyfile = configure_file(input : 'libinput.doxygen.in',
 			  install : false)
 
 custom_target('doxygen',
-	      input : [ doxyfile, readme ] + src_doxygen,
+	      input : [ doxyfile, readme, doc_git_version] + src_doxygen,
 	      output : [ 'Documentation' ],
 	      command : [ doxygen, doxyfile ],
 	      install : false,
-	      depends: [doxyfiles, readme],
+	      depends: [doxyfiles, readme, doc_git_version],
 	      build_by_default : true)