[PATCH libinput] Add doc to discourage use of libinput_device_get_output_name()

[Peter Hutterer]

This is a leftover from when libinput was part of weston and we could
interpret properties correctly. Realistically, the only way this could work
with libinput as external library is if we define precisely what the
definition of an output is. Practically, it's a lot easier to just throw up
our hands and leave it all to the caller.

https://bugs.freedesktop.org/show_bug.cgi?id=100707

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
Reviewed-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
---
Pekka: I added the last sentence on top of the patch from 100707, but left
your rev-by on it. If you disagree with that, we'll have to figure it out
over a bout of fisticuffs in the sand pit ;)

 src/libinput.h | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/libinput.h b/src/libinput.h
index aa30cfa..430fe18 100644
--- a/src/libinput.h
+++ b/src/libinput.h
@@ -3491,6 +3491,14 @@ libinput_device_get_id_vendor(struct libinput_device *device);
  * beyond the boundaries of this output. An absolute device has its input
  * coordinates mapped to the extents of this output.
  *
+ * @note <b>Use of this function is discouraged.</b> Its return value is not
+ * precisely defined and may not be understood by the caller or may be
+ * insufficient to map the device. Instead, the system configuration could
+ * set a udev property the caller understands and interprets correctly. The
+ * caller could then obtain device with libinput_device_get_udev_device()
+ * and query it for this property. For more complex cases, the caller
+ * must implement monitor-to-device association heuristics.
+ *
  * @return The name of the output this device is mapped to, or NULL if no
  * output is set
  */
-- 
2.9.3