Re: [PATCH libinput 3/7] doc: move the struct declarations to the top

[Yong Bakos]

> On Jun 6, 2016, at 1:50 AM, Peter Hutterer  wrote:
> 
> They don't define anything, move them to the top so we don't have ordering
> requirements of the stuff that actually uses those as parameters.
> 
> Signed-off-by: Peter Hutterer 

FWIW,
Reviewed-by: Yong Bakos 

yong


> ---
> src/libinput.h | 252 -
> 1 file changed, 126 insertions(+), 126 deletions(-)
> 
> diff --git a/src/libinput.h b/src/libinput.h
> index dcfa09f..212bf4a 100644
> --- a/src/libinput.h
> +++ b/src/libinput.h
> @@ -39,6 +39,132 @@ extern "C" {
> 
> /**
>  * @ingroup base
> + * @struct libinput
> + *
> + * A handle for accessing libinput. This struct is refcounted, use
> + * libinput_ref() and libinput_unref().
> + */
> +struct libinput;
> +
> +/**
> + * @ingroup device
> + * @struct libinput_device
> + *
> + * A base handle for accessing libinput devices. This struct is
> + * refcounted, use libinput_device_ref() and libinput_device_unref().
> + */
> +struct libinput_device;
> +
> +/**
> + * @ingroup device
> + * @struct libinput_device_group
> + *
> + * A base handle for accessing libinput device groups. This struct is
> + * refcounted, use libinput_device_group_ref() and
> + * libinput_device_group_unref().
> + */
> +struct libinput_device_group;
> +
> +/**
> + * @ingroup seat
> + * @struct libinput_seat
> + *
> + * The base handle for accessing libinput seats. This struct is
> + * refcounted, use libinput_seat_ref() and libinput_seat_unref().
> + */
> +struct libinput_seat;
> +
> +/**
> + * @ingroup device
> + * @struct libinput_tablet_tool
> + *
> + * An object representing a tool being used by a device with the @ref
> + * LIBINPUT_DEVICE_CAP_TABLET_TOOL 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, see @ref tablet-serial-numbers.
> + *
> + * This struct is refcounted, use libinput_tablet_tool_ref() and
> + * libinput_tablet_tool_unref().
> + */
> +struct libinput_tablet_tool;
> +
> +/**
> + * @ingroup event
> + * @struct libinput_event
> + *
> + * The base event type. Use libinput_event_get_pointer_event() or similar to
> + * get the actual event type.
> + *
> + * @warning Unlike other structs events are considered transient and
> + * not refcounted.
> + */
> +struct libinput_event;
> +
> +/**
> + * @ingroup event
> + * @struct libinput_event_device_notify
> + *
> + * An event notifying the caller of a device being added or removed.
> + */
> +struct libinput_event_device_notify;
> +
> +/**
> + * @ingroup event_keyboard
> + * @struct libinput_event_keyboard
> + *
> + * A keyboard event representing a key press/release.
> + */
> +struct libinput_event_keyboard;
> +
> +/**
> + * @ingroup event_pointer
> + * @struct libinput_event_pointer
> + *
> + * A pointer event representing relative or absolute pointer movement,
> + * a button press/release or scroll axis events.
> + */
> +struct libinput_event_pointer;
> +
> +/**
> + * @ingroup event_touch
> + * @struct libinput_event_touch
> + *
> + * Touch event representing a touch down, move or up, as well as a touch
> + * cancel and touch frame events. Valid event types for this event are @ref
> + * LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_MOTION, @ref
> + * LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_CANCEL and @ref
> + * LIBINPUT_EVENT_TOUCH_FRAME.
> + */
> +struct libinput_event_touch;
> +
> +/**
> + * @ingroup event_tablet
> + * @struct libinput_event_tablet_tool
> + *
> + * Tablet tool event representing an axis update, button press, or tool
> + * update. Valid event types for this event are @ref
> + * LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref
> + * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY and @ref
> + * LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
> + */
> +struct libinput_event_tablet_tool;
> +
> +/**
> + * @ingroup event_tablet_pad
> + * @struct libinput_event_tablet_pad
> + *
> + * Tablet pad event representing a button press, or ring/strip update on
> + * the tablet pad itself. Valid event types for this event are @ref
> + * LIBINPUT_EVENT_TABLET_PAD_BUTTON, @ref LIBINPUT_EVENT_TABLET_PAD_RING and
> + * @ref LIBINPUT_EVENT_TABLET_PAD_STRIP.
> + */
> +struct libinput_event_tablet_pad;
> +
> +/**
> + * @ingroup base
>  *
>  * Log priority for internal logging messages.
>  */
> @@ -167,23 +293,6 @@ enum libinput_tablet_pad_strip_axis_source {
> 
> /**
>  * @ingroup device
> - * @struct libinput_tablet_tool
> - *
> - * An object representing a tool being used by a device with the @ref
> - * LIBINPUT_DEVICE_CAP_TABLET_TOOL 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, s

[PATCH libinput 3/7] doc: move the struct declarations to the top

[Peter Hutterer]

They don't define anything, move them to the top so we don't have ordering
requirements of the stuff that actually uses those as parameters.

Signed-off-by: Peter Hutterer 
---
 src/libinput.h | 252 -
 1 file changed, 126 insertions(+), 126 deletions(-)

diff --git a/src/libinput.h b/src/libinput.h
index dcfa09f..212bf4a 100644
--- a/src/libinput.h
+++ b/src/libinput.h
@@ -39,6 +39,132 @@ extern "C" {
 
 /**
  * @ingroup base
+ * @struct libinput
+ *
+ * A handle for accessing libinput. This struct is refcounted, use
+ * libinput_ref() and libinput_unref().
+ */
+struct libinput;
+
+/**
+ * @ingroup device
+ * @struct libinput_device
+ *
+ * A base handle for accessing libinput devices. This struct is
+ * refcounted, use libinput_device_ref() and libinput_device_unref().
+ */
+struct libinput_device;
+
+/**
+ * @ingroup device
+ * @struct libinput_device_group
+ *
+ * A base handle for accessing libinput device groups. This struct is
+ * refcounted, use libinput_device_group_ref() and
+ * libinput_device_group_unref().
+ */
+struct libinput_device_group;
+
+/**
+ * @ingroup seat
+ * @struct libinput_seat
+ *
+ * The base handle for accessing libinput seats. This struct is
+ * refcounted, use libinput_seat_ref() and libinput_seat_unref().
+ */
+struct libinput_seat;
+
+/**
+ * @ingroup device
+ * @struct libinput_tablet_tool
+ *
+ * An object representing a tool being used by a device with the @ref
+ * LIBINPUT_DEVICE_CAP_TABLET_TOOL 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, see @ref tablet-serial-numbers.
+ *
+ * This struct is refcounted, use libinput_tablet_tool_ref() and
+ * libinput_tablet_tool_unref().
+ */
+struct libinput_tablet_tool;
+
+/**
+ * @ingroup event
+ * @struct libinput_event
+ *
+ * The base event type. Use libinput_event_get_pointer_event() or similar to
+ * get the actual event type.
+ *
+ * @warning Unlike other structs events are considered transient and
+ * not refcounted.
+ */
+struct libinput_event;
+
+/**
+ * @ingroup event
+ * @struct libinput_event_device_notify
+ *
+ * An event notifying the caller of a device being added or removed.
+ */
+struct libinput_event_device_notify;
+
+/**
+ * @ingroup event_keyboard
+ * @struct libinput_event_keyboard
+ *
+ * A keyboard event representing a key press/release.
+ */
+struct libinput_event_keyboard;
+
+/**
+ * @ingroup event_pointer
+ * @struct libinput_event_pointer
+ *
+ * A pointer event representing relative or absolute pointer movement,
+ * a button press/release or scroll axis events.
+ */
+struct libinput_event_pointer;
+
+/**
+ * @ingroup event_touch
+ * @struct libinput_event_touch
+ *
+ * Touch event representing a touch down, move or up, as well as a touch
+ * cancel and touch frame events. Valid event types for this event are @ref
+ * LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_MOTION, @ref
+ * LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_CANCEL and @ref
+ * LIBINPUT_EVENT_TOUCH_FRAME.
+ */
+struct libinput_event_touch;
+
+/**
+ * @ingroup event_tablet
+ * @struct libinput_event_tablet_tool
+ *
+ * Tablet tool event representing an axis update, button press, or tool
+ * update. Valid event types for this event are @ref
+ * LIBINPUT_EVENT_TABLET_TOOL_AXIS, @ref
+ * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY and @ref
+ * LIBINPUT_EVENT_TABLET_TOOL_BUTTON.
+ */
+struct libinput_event_tablet_tool;
+
+/**
+ * @ingroup event_tablet_pad
+ * @struct libinput_event_tablet_pad
+ *
+ * Tablet pad event representing a button press, or ring/strip update on
+ * the tablet pad itself. Valid event types for this event are @ref
+ * LIBINPUT_EVENT_TABLET_PAD_BUTTON, @ref LIBINPUT_EVENT_TABLET_PAD_RING and
+ * @ref LIBINPUT_EVENT_TABLET_PAD_STRIP.
+ */
+struct libinput_event_tablet_pad;
+
+/**
+ * @ingroup base
  *
  * Log priority for internal logging messages.
  */
@@ -167,23 +293,6 @@ enum libinput_tablet_pad_strip_axis_source {
 
 /**
  * @ingroup device
- * @struct libinput_tablet_tool
- *
- * An object representing a tool being used by a device with the @ref
- * LIBINPUT_DEVICE_CAP_TABLET_TOOL 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, see @ref tablet-serial-numbers.
- *
- * This struct is refcounted, use libinput_tablet_tool_ref() and
- * libinput_tablet_tool_unref().
- */
-struct libinput_tablet_tool;
-
-/**
- * @ingroup device
  *
  * Available tool types for a device with the @ref
  * LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. The tool type defines the 
default
@@ -404,115 +513,6 @@ enum libinput_event_type {
 };
 
 /**
- * @