added doxygen for interfaces

- a brief description of all interface functions

Signed-off-by: Manuel Traut <manut@mecka.net>

3 files changed, 92 insertions, 2 deletions

diff --git a/interfaces/common.idl b/interfaces/common.idl
index 7e6266c..f80b9f7 100644
--- a/interfaces/common.idl
+++ b/interfaces/common.idl
@@ -1,14 +1,29 @@
 #ifndef DISTIO_COMMON_IDL
 #define DISTIO_COMMON_IDL
 
+/**
+ * @brief shared between different modules
+ *
+ * - definitions for error handling
+ *
+ * @author Manuel Traut <manut@mecka.net>
+ * @copyright GPLv2
+ *
+ */
 module Common {
 
+/**
+ * @brief kind of error
+ */
 	enum Error_code {
 		SUCCESS,
 		EINVAL,
 		ENOTSUPPORTED
 	};
 
+/**
+ * @brief used for filtering and classification
+ */
 	enum Error_level {
 		DEBUG,
 		INFO,
@@ -17,16 +32,25 @@ module Common {
 		CRITICAL
 	};
 
+/**
+ * @brief describes when the error was detected
+ *  (it's helpful to sync all boards with ntp)
+ */
 	struct Error_timestamp {
 		longlong seconds;
 		long nanoseconds;
 	};
 
+/**
+ * @brief description of an error
+ */
 	struct Error {
 		Error_code code;
 		Error_level level;
 		Error_timestamp time;
+		/** id of the digital/analog IO or the IO device */
 		long module_id;
+		/** a human readable description which can be displayed in GUIs */
 		string description;
 	};
 
diff --git a/interfaces/controller.idl b/interfaces/controller.idl
index 3410ab6..f1719bf 100644
--- a/interfaces/controller.idl
+++ b/interfaces/controller.idl
@@ -4,18 +4,45 @@
 #include "common.idl"
 #include "io.idl"
 
+/**
+ * @brief logical view of IO's and Devices (not HW specific)
+ *
+ * @author Manuel Traut <manut@mecka.net>
+ * @copyright GPLv2
+ */
+
 module Controller {
 
+/**
+ * @brief manage io/device lists, error handling
+ *
+ * - all modules need to register their IOs and devices
+ * - registered IOs and devices can be obtained
+ */
 	interface Manager {
+		/** returns list of registered digital IOs */
 		Common::Error digital (out IO::Digital_list io_list);
+		/** returns list of registered analog IOs */
 		Common::Error analog (out IO::Analog_list io_list);
+		/** returns list of registered devices */
 		Common::Error device (out IO::Device_list dev_list);
+		/** register a digital IO */
 		Common::Error register_io_digital (in IO::Analog io_ana);
+		/** register a analog IO */
 		Common::Error register_io_analog (in IO::Digital io_dig);
+		/** register a device */
 		Common::Error register_io_device (in IO::Device io_dev);
+		/** unregister a digital IO */
 		Common::Error unregister_io_digital (in IO::Digital io_dig);
+		/** unregister a analog IO */
 		Common::Error unregister_io_analog (in IO::Analog io_ana);
+		/** unregister a device */
 		Common::Error unregister_io_device (in IO::Device io_dev);
+		/** used by modules to send errors to a central point
+		 *   The implementation of this function could:
+		 *    - thispatch errors to a GUI
+		 *    - log the errors e.g. with log4*
+		 */
 		void log_error (in Common::Error error);
 	};
 
diff --git a/interfaces/io.idl b/interfaces/io.idl
index 435ea01..86e6f4f 100644
--- a/interfaces/io.idl
+++ b/interfaces/io.idl
@@ -3,49 +3,77 @@
 
 #include "common.idl"
 
+/**
+ * @brief the implementation of these interfaces are responsible for
+ *	controlling the I/O hardware
+ *
+ * @author Manuel Traut <manut@mecka.net>
+ * @copyright GPLv2
+ */
+
 module IO {
 
 	interface Device;
 
+	/** what should trigger a callback? */
 	enum Digital_trigger {
 		TRIGGER_EDGE,
 		TRIGGER_RISING_EDGE,
 		TRIGGER_FALLING_EDGE
 	};
 
+	/** a digital input or output pin */
 	interface Digital {
+		/** get the name of the hardware which is connected to this pin */
 		Common::Error name (out string name);
+		/** set this pin (fails if it's a digital input) */
 		Common::Error set ();
+		/** reset this pin (fails if it's a digital input) */
 		Common::Error reset ();
+		/** get the value of the pin ( 0 = reset, rest = set */
 		Common::Error get (out long value);
+		/** register a callback that is called if the state of the pin changes */
 		Common::Error register_callback (in Device dev, in Digital_trigger trigger);
+		/** the id is given by Controller::Manager during registration */
 		attribute long id;
 	};
 
 	typedef sequence<Digital> Digital_list;
 
+	/** what should trigger a callback? */
 	struct Analog_trigger {
+		/** used internal to store analog value of the last trigger */
 		long last_value;
+		/** e.g. if current_value > last_value + jitter -> execute callback */
 		long jitter;
 	};
 
+	/** an analog input or output pin */
 	interface Analog {
+		/** name of the hardware which is connected to the pin */
 		Common::Error name (out string name);
+		/** minimum allowed value */
 		Common::Error min (out long min);
+		/** maximum allowd value */
 		Common::Error max (out long max);
+		/** set new value (may fail if out of range or pin is an input) */
 		Common::Error set (in long value);
+		/** get analog value of the pin */
 		Common::Error get (out long value);
+		/** register a callback that is called if the trigger matches */
 		Common::Error register_callback (in Device dev, in Analog_trigger trigger);
 		attribute long id;
 	};
 
 	typedef sequence<Analog> Analog_list;
 
+	/** list of functions of all devices - new ones can be added if needed */
 	enum Dev_function_id {
 		DEV_START,
 		DEV_STOP
 	};
 
+	/** definition to control the device, e.g. start or stop it */
 	struct Dev_function {
 		string description;
 		long value;
@@ -54,14 +82,25 @@ module IO {
 
 	typedef sequence<Dev_function> Dev_function_list;
 
+	/** a device could have several io's and can export functions which can be
+	 *   controlled by a HID device or GUI
+	 */
 	interface Device {
+		/** name of the device */
 		Common::Error name (out string name);
+		/** to execute a device specific function pass the Dev_function descriotion
+		 *		(retrived by (functions ()) as parameter
+		 */
 		Common::Error execute (in Dev_function func);
+		/** returns all device specific function descriptions */
 		Common::Error functions (out Dev_function_list funcs);
+		/** called by the Digital object if this object is registered as a
+		 *		callback and the trigger hits */
 		Common::Error callback_digital (in Digital io_dig);
+		/** called by the Digital object if this object is registered as a
+		 *		callback and the trigger hits */
 		Common::Error callback_analog (in Analog io_ana);
-		attribute Analog_list io_ana;
-		attribute Digital_list io_dig;
+		/** ID is given by Controller::Manager during registration */
 		attribute long id;
 	};