Added doxygen docu for touch module

common/touch/touch.h

@@ -1,39 +1,113 @@
+
+/**
+ * @defgroup touch Touch
+ * The Touch module provides access to the touch controller, and executes a callback if a certain region is touched
+ */
+
+
+/**
+ * @addtogroup touch
+ */
+/*@{*/
+
+
 #ifndef TOUCH_H
 #define TOUCH_H
 
-
 #include<stdbool.h>
 #include<stdint.h>
 
+/**
+Enum to describe the current Touch State. \sa touch_add_raw_event
+ */
+typedef enum {
+	TOUCH_UP, //!< The display is currently not touched
+	TOUCH_DOWN //!< The display is currently touched at some point
+} TOUCH_STATE ;
 
-typedef enum {TOUCH_UP,TOUCH_DOWN} TOUCH_STATE ;
-typedef enum {NONE=0x00,PEN_DOWN=0x01, PEN_UP=0x02, PEN_ENTER=0x04, PEN_LEAVE=0x08,PEN_MOVE=0x10} TOUCH_ACTION;
+/**
+ * Enum to describe the hooked actions for which you want to receive events for. You can OR-combine them. \sa touch_register_area
+ */
+typedef enum {
+	NONE=0x00,      //!< Do not receive any events
+	PEN_DOWN=0x01,  //!< Receive an event when the pen goes down inside the region
+	PEN_UP=0x02,    //!< Receive an event when the pen goes up inside the region
+	PEN_ENTER=0x04, //!< Receive an event when the pen enters the region (pen was down before)
+	PEN_LEAVE=0x08, //!< Receive an event when the pen leaves the region (pen was inside region before)
+	PEN_MOVE=0x10   //!< Receive an event when the pen moves inside the region (pen is down)
+} TOUCH_ACTION;
 
+/**
+ * Prototype for Event Listeners (called for every occurring, hooked action)
+ * @param touchArea The pointer to the touchArea in which the event occurred
+ * @param triggeredAction The Action which occurred
+ */
 typedef void (*TOUCH_CALLBACK)(void* touchArea, TOUCH_ACTION triggeredAction);
 
+/**
+ * Structure to configure a Touch Area
+ */
 typedef struct {
-        TOUCH_ACTION hookedActions; //Actions to listen to
-        uint16_t x1; //Top Left X Coordiate of Area
-        uint16_t y1; //Top Left Y Coordiate of Area
-        uint16_t x2; //Bottom Right X Coordiate of Area
-        uint16_t y2; //Bottom Right Y Coordiate of Area
-        TOUCH_CALLBACK callback; //Callback
-        uint8_t flags; //Internal Used, don't change
+        TOUCH_ACTION hookedActions; //!< Actions to listen to
+        uint16_t x1; //!< Top Left X-Coordinate of Area
+        uint16_t y1; //!< Top Left Y-Coordinate of Area
+        uint16_t x2; //!< Bottom Right X-Coordinate of Area
+        uint16_t y2; //!< Bottom Right Y-Coordinate of Area
+        TOUCH_CALLBACK callback; //!< Callback
+        uint8_t flags; //!< For internal Used, don't change, don't initialize
 } TOUCH_AREA_STRUCT;
 
 
+/**
+ * Struct which represents a 2D point on the display
+ */
 typedef struct {
-	uint16_t x;
-	uint16_t y;
+	uint16_t x; //!< The X-Coordinate of the point
+	uint16_t y; //!< The Y-Coordinate of the point
 } POINT_STRUCT;
 
-
+/**
+ * Initializes the Touch Controller. Call this method before using any touch_* functions
+ * @return true on success
+ */
 bool touch_init();
+
+/**
+ * Processes a native touch event. You may call this function from an (SPI)-Interrupt
+ * @param x The x-Coordinate of the touch event
+ * @param y The y-Coordinate of the touch event
+ * @param state Whether the pen is up or down
+ * @return True on success
+ */
 bool touch_add_raw_event(uint16_t x, uint16_t y,TOUCH_STATE state);
+
+/**
+ * Checks whether or not we have memory to manage and track additional "num" TOUCH_AREAs
+ * @param num The number of touch areas you would like to allocate
+ * @return True if there's enough memory to allocate num TOUCH_AREAs
+ */
 bool touch_have_empty(unsigned char num);
+
+/**
+ * Registers a new touch Area. You will receive events for this area from now on.
+ * @param area A pointer to the configured TOUCH_AREA struct
+ * @return True if everything was successful and the TOUCH_AREA will be monitored from now on
+ */
 bool touch_register_area(TOUCH_AREA_STRUCT* area);
+
+/**
+ * Unregisters a touch area. You will no longer receive events for this area
+ * @param area A pointer to the TOUCH_AREA instance
+ */
 void touch_unregister_area(TOUCH_AREA_STRUCT* area);
+
+/**
+ * Gets the last touched point
+ * @return The Coordinates of the last touched points
+ */
 POINT_STRUCT touch_get_last_point();
 
 
 #endif /* TOUCH_H */
+
+/*@}*/