added more API documentation to backends/interfaces

7 files changed, 40 insertions, 20 deletions

diff --git a/src/charon/config/backend_manager.h b/src/charon/config/backend_manager.h
index 07cd9c541..4c00e4b13 100644
--- a/src/charon/config/backend_manager.h
+++ b/src/charon/config/backend_manager.h
@@ -34,12 +34,16 @@ typedef struct backend_manager_t backend_manager_t;
 
 
 /**
- * @brief A multiplexer to use multiple backends.
+ * @brief A loader and multiplexer to use multiple backends.
  *
- * Charon allows the use of multiple backend_manager backends simultaneously. To
+ * Charon allows the use of multiple configuration backends simultaneously. To
  * access all this backends by a single call, this class wraps multiple
- * backends behind a single object.
- * Backends may be registered and unregister at runtime dynamically.
+ * backends behind a single object. It is also responsible for loading
+ * the backend modules and cleaning them up.
+ * A backend may be writeable or not. All backends implement the backend_t
+ * interface, those who are writeable additionally implement the
+ * writeable_backend_t interface. Adding configs to the backend_manager will
+ * be redirected to the first writeable backend.
  * @verbatim
 
    +---------+      +-----------+         +--------------+     |
@@ -106,7 +110,7 @@ struct backend_manager_t {
 };
 
 /**
- * @brief Create a new instance of the manager and loads all backends.
+ * @brief Creates a new instance of the manager and loads all backends.
  *
  * @return		backend_manager instance
  *
diff --git a/src/charon/config/backends/backend.h b/src/charon/config/backends/backend.h
index 5f9543028..14ab215e8 100644
--- a/src/charon/config/backends/backend.h
+++ b/src/charon/config/backends/backend.h
@@ -33,12 +33,12 @@ typedef struct backend_t backend_t;
 /**
  * @brief The interface for a configuration backend.
  *
- * A configuration backend is registered in the cfg_store. It does the actual
- * configuration lookup for the method it implements. See cfg_store_t for
+ * A configuration backend is loaded by the backend_manager. It does the actual
+ * configuration lookup for the method it implements. See backend_manager_t for
  * more information.
  *
  * @b Constructors:
- * - none, use implementations of backend_t.
+ * - implementations constructors
  * 
  * @ingroup backends
  */
diff --git a/src/charon/config/backends/local_backend.h b/src/charon/config/backends/local_backend.h
index f3538eab2..b33c6443b 100644
--- a/src/charon/config/backends/local_backend.h
+++ b/src/charon/config/backends/local_backend.h
@@ -29,7 +29,7 @@ typedef struct local_backend_t local_backend_t;
 #include <config/backends/writeable_backend.h>
 
 /**
- * @brief An in-memory backend to store configuration information.
+ * @brief An in-memory backend to store configurations.
  *
  * The local_backend_t stores the configuration in a simple list. It
  * implements both, backend_t and writeable_backend_t.
@@ -50,7 +50,7 @@ struct local_backend_t {
 /**
  * @brief Create a backend_t instance implemented as local backend.
  *
- * @return backend instance.
+ * @return backend instance
  * 
  * @ingroup backends
  */
diff --git a/src/charon/config/backends/writeable_backend.h b/src/charon/config/backends/writeable_backend.h
index 4771a0cff..ea62f62c9 100644
--- a/src/charon/config/backends/writeable_backend.h
+++ b/src/charon/config/backends/writeable_backend.h
@@ -29,7 +29,7 @@ typedef struct writeable_backend_t writeable_backend_t;
 #include <config/backends/backend.h>
 
 /**
- * @brief A writeable backend extends the backend by modification functions.
+ * @brief A writeable backend extends backend_t by modification functions.
  *
  * @b Constructors:
  *  - writeable_backend_create()
diff --git a/src/charon/control/interface_manager.h b/src/charon/control/interface_manager.h
index 57121c833..ccd9c4979 100644
--- a/src/charon/control/interface_manager.h
+++ b/src/charon/control/interface_manager.h
@@ -26,7 +26,7 @@
 #include <bus/bus.h>
 
 /**
- * callback to log things triggered by interface_manager
+ * callback to log things triggered by interface_manager.
  *
  * @param param			echoed parameter supplied when function invoked
  * @param signal		type of signal
@@ -43,8 +43,23 @@ typedef bool(*interface_manager_cb_t)(void* param, signal_t signal, level_t leve
 typedef struct interface_manager_t interface_manager_t;
 
 /**
- * @brief The interface_manager controls the daemon.
+ * @brief The interface_manager loads control interfaces and has helper methods.
  *
+ * One job of the interface manager is to load pluggable control interface
+ * modules, implemented as interface_t.
+ * @verbatim
+
+   +---------+      +------------+         +--------------+     |
+   |         |      |            |<----- +--------------+ |     |
+   | daemon  |<-----| interface- |     +--------------+ |-+  <==|==> IPC
+   |  core   |      | manager    |<----|  interfaces  |-+       |
+   |         |<-----|            |     +--------------+         |
+   |         |      |            |                              |
+   +---------+      +------------+                              |
+
+   @endverbatim
+ * The manager does not really use the interfaces, instead, the interface
+ * use the manager to fullfill their tasks (initiating, terminating, ...). 
  * The interface_manager starts actions by creating jobs. It then tries to
  * evaluate the result of the operation by listening on the bus.
  * 
@@ -82,7 +97,7 @@ struct interface_manager_t {
 
 
 /**
- * @brief Create a interface_manager instance and loads all interface modules.
+ * @brief Creates a interface_manager instance and loads all interface modules.
  * 
  * @return 			interface_manager_t object
  * 
diff --git a/src/charon/control/interfaces/interface.h b/src/charon/control/interfaces/interface.h
index 1949556cc..955f4a4eb 100644
--- a/src/charon/control/interfaces/interface.h
+++ b/src/charon/control/interfaces/interface.h
@@ -27,6 +27,10 @@ typedef struct interface_t interface_t;
 
 /**
  * @brief Interface for a controller.
+ *
+ * An interface controls the daemon by calling functions on the
+ * interface_manager. All interfaces are manager by the interface_manager
+ * in a generic way, so they need their own class.
  * 
  * @b Constructors:
  * - interface_create() of one of the modules
diff --git a/src/charon/control/interfaces/stroke_interface.h b/src/charon/control/interfaces/stroke_interface.h
index f189048bd..5eaa32412 100644
--- a/src/charon/control/interfaces/stroke_interface.h
+++ b/src/charon/control/interfaces/stroke_interface.h
@@ -28,13 +28,10 @@ typedef struct stroke_interface_t stroke_interface_t;
 #include <control/interfaces/interface.h>
 
 /**
- * @brief Stroke is a configuration and control interface which
- * allows other processes to modify charons behavior.
+ * @brief Simple configuration interface using unix-sockets.
  * 
- * stroke_t allows config manipulation (as whack in pluto). Configurations
- * are stored in a special backend, the in-memory local_backend_t.
- * Messages of type stroke_msg_t's are sent over a unix socket
- * (/var/run/charon.ctl).
+ * Stroke is a home-brewed communication interface inspired by whack. It
+ * uses a unix socket (/var/run/charon.ctl).
  * 
  * @b Constructors:
  * - stroke_create()