Add documentation to structs and functions in grail.h

Signed-off-by: Henrik Rydberg <rydberg@euromail.se>

1 files changed, 138 insertions, 5 deletions

diff --git a/include/grail.h b/include/grail.h
index c77a6e3..ae3a73f 100644
--- a/include/grail.h
+++ b/include/grail.h
@@ -37,23 +37,59 @@
 #define GRAIL_STATUS_UPDATE     1
 #define GRAIL_STATUS_END        2
 
-typedef float grail_prop_t;
-typedef __u64 grail_time_t;
-
+typedef float grail_prop_t;             /* gesture properties */
+typedef __u64 grail_time_t;             /* time in milliseconds */
+
+/**
+ * struct grail_coord - coordinate in bounding box units
+ * @x: the horizontal position (bbox units)
+ * @y: the vertical position (bbox units)
+ */
 struct grail_coord {
         float x, y;
 };
 
+
+/**
+ * struct grail_client_id - Gesture client information
+ * @client: Client id
+ * @root: Root window
+ * @event: Window to route events to
+ * @child: Window the event occured in
+ *
+ * This struct is treated opaquely, and only has meaning to the gesture
+ * client. Details are subject to change.
+ */
 struct grail_client_id {
         int client;
         int root, event, child;
 };
 
+/**
+ * struct grail_client_info - Gesture request information
+ * @id: Gesture client id
+ * @mask: Gestures the client is listening to
+ */
 struct grail_client_info {
         struct grail_client_id id;
         grail_mask_t mask[DIM_GRAIL_TYPE_BYTES];
 };
 
+/**
+ * struct grail_event - Gesture event
+ * @type: The gesture type
+ * @id: Unique identifier foof the gesture instance
+ * @status: Gesture status (begin, update, end)
+ * @ntouch: Number of current touches
+ * @nprop: Number of properties in the gesture
+ * @pos: Focus point of the gesture (bbox coordinates)
+ * @touch: Array of individual touch information
+ * @client_id: The gesture client to route the gesture to
+ * @time: Time of event (milliseconds)
+ * @prop: Array of properties of the event
+ *
+ * Gesture events are passed to the client via the gesture() callback.
+ */
 struct grail_event {
         int type;
         int id;
@@ -66,6 +102,25 @@ struct grail_event {
         grail_prop_t prop[DIM_GRAIL_PROP];
 };
 
+/**
+ * struct grail - Main grail device
+ * @get_clients: Called at the onset of new gestures to retrieve the list
+ * of listening clients.
+ * @event: Callback for kernel events passing through grail.
+ * @gesture: Main gesture callback.
+ * @impl: Grail implementation details.
+ * @gin: Gesture instatiation details.
+ * @gru: Gesture recognition details.
+ * @priv: Generic pointer to user-defined content.
+ *
+ * The grail device pulls events from the underlying device, detects
+ * gestures, and passes them on to the client via the gesture()
+ * callback. Events that are not gesture or for other reasons held back are
+ * passed on via the event() callback. The user provides information about
+ * windows and listening clients via the get_clients callback, which is
+ * called during gesture instantiation.
+ *
+ */
 struct grail {
         int (*get_clients)(struct grail *ge,
                            struct grail_client_info *client, int max_clients,
@@ -81,18 +136,96 @@ struct grail {
         void *priv;
 };
 
+/**
+ * grail_open - open a grail device
+ * @ge: the grail device to open
+ * @fd: file descriptor of the kernel device
+ *
+ * Initialize the internal grail structures and configure it by reading the
+ * protocol capabilities through the file descriptor.
+ *
+ * The callbacks, parameters and priv pointer should be set prior to this
+ * call.
+ *
+ * Returns zero on success, negative error number otherwise.
+ */
 int grail_open(struct grail *ge, int fd);
+
+/**
+ * grail_idle - check state of kernel device
+ * @ge: the grail device in use
+ * @fd: file descriptor of the kernel device
+ * @ms: number of milliseconds to wait for activity
+ *
+ * Returns true if the device is idle, i.e., there are no fetched
+ * events in the pipe and there is nothing to fetch from the device.
+ */
 int grail_idle(struct grail *ge, int fd, int ms);
+
+/**
+ * grail_pull - pull and process available events from the kernel device
+ * @ge: the grail device in use
+ * @fd: file descriptor of the kernel device
+ *
+ * Pull all available events and process them. The grail callbacks are
+ * invoked during this call.
+ *
+ * The underlying file descriptor must have O_NONBLOCK set, or this method
+ * will not return until the file is closed.
+ *
+ * On success, returns the number of events read. Otherwise,
+ * a standard negative error number is returned.
+ */
 int grail_pull(struct grail *ge, int fd);
+
+/**
+ * grail_close - close the grail device
+ * @ge: the grail device to close
+ * @fd: file descriptor of the kernel device
+ *
+ * Deallocates all memory associated with grail, and clears the grail
+ * structure.
+ */
 void grail_close(struct grail *ge, int fd);
 
+/**
+ * grail_set_bbox - set the grail unit bounding box
+ * @ge: the grail device in use
+ * @min: the minimum (lower-left) corner of the bounding box
+ * @max: the maximum (upper-right) corner of the bounding box
+ *
+ * Sets the box within which the device coordinates should be presented.
+ */
 void grail_set_bbox(struct grail *ge,
                     const struct grail_coord *min,
                     const struct grail_coord *max);
 
+/**
+ * grail_filter_abs_events - filter kernel motion events
+ * @ge: the grail device in use
+ * @usage: When true, filter kernel motion events.
+ *
+ * Single-finger pointer events are treated as pointer gestures in
+ * grail. When filter_motion_events is non-zero, the kernel events
+ * corresponding to pointer movement are removed from the event
+ * stream.
+ *
+ */
+void grail_filter_abs_events(struct grail *ge, int usage);
+
+/**
+ * grail_get_units - get device coordinate ranges
+ * @ge: the grail device in use
+ * @min: minimum x and y coordinates
+ * @max: maximum x and y coordinates
+ *
+ * The grail event attributes pos, touch_major, touch_minor,
+ * width_major, and width_minor are all given in device coordinate
+ * units, unless specified otherwise using the grail_set_bbox()
+ * function. This function reports the device coordinate ranges.
+ *
+ */
 void grail_get_units(const struct grail *ge,
                      struct grail_coord *min, struct grail_coord *max);
 
-void grail_filter_abs_events(struct grail *ge, int usage);
-
 #endif