Made all in-source documentation Gtk-Doc conformant

9 files changed, 207 insertions, 228 deletions

diff --git a/src/kiro-client.c b/src/kiro-client.c
index 01f4fb0..b0f5d45 100644
--- a/src/kiro-client.c
+++ b/src/kiro-client.c
@@ -16,15 +16,6 @@
    Franklin St, Fifth Floor, Boston, MA 02110, USA
 */
 
-/**
- * SECTION: kiro-client
- * @Short_description: KIRO RDMA Client / Consumer
- * @Title: KiroClient
- *
- * KiroClient implements the client / active / consumer side of the the RDMA
- * Communication Channel. It uses a KIRO-CLIENT to manage data read from the Server.
- */
-
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
diff --git a/src/kiro-client.h b/src/kiro-client.h
index 1941c7a..ff6c00f 100644
--- a/src/kiro-client.h
+++ b/src/kiro-client.h
@@ -54,13 +54,6 @@ struct _KiroClient {
     KiroClientPrivate *priv;
 };
 
-
-/**
- * IbvConnectorInterface:
- *
- * Base interface for IbvConnectors.
- */
-
 struct _KiroClientClass {
 
     GObjectClass parent_class;
@@ -70,28 +63,26 @@ struct _KiroClientClass {
 
 
 /* GObject and GType functions */
-/**
- * kiro_client_get_type: (skip)
- * Returns: GType of #KiroClient
- */
 GType       kiro_client_get_type            (void);
 
 /**
- * kiro_client_new - Creates a new #KiroClient
+ * kiro_client_new:
+ *
+ * Creates a new, unconnected #KiroClient and returns a pointer to it.
+ *
  * Returns: (transfer full): A pointer to a new #KiroClient
- * Description:
- *   Creates a new, unconnected #KiroClient and returns a pointer to it.
  * See also:
  *   kiro_client_free, kiro_client_connect
  */
 KiroClient* kiro_client_new                 (void);
 
 /**
- * kiro_client_free - 'Destroys' the given #KiroClient
+ * kiro_client_free:
  * @client: (transfer none): The #KiroClient that is to be freed
- * Description:
+ *
  *   Transitions the #KiroServer through all necessary shutdown routines and
  *   frees the object memory.
+ *
  * Note:
  *   The memory content that has been transfered from the server is
  *   automatically freed when calling this function. If you want to continue
@@ -107,15 +98,17 @@ void        kiro_client_free                (KiroClient *client);
 /* client functions */
 
 /**
- * kiro_client_connect - Connect a #KiroClient to a Server
+ * kiro_client_connect:
  * @client: (transfer none): The #KiroClient to connect
  * @dest_addr: (transfer none): The address of the target server
  * @dest_port: (transfer none): The port of the target server
- * Returns:
- *   0 if the connection was successful, -1 in case of connection error
- * Description:
+ *
  *   Connects the given #KiroClient to a KIRO server described by @dest_addr and
  *   @dest_port.
+ *
+ * Returns:
+ *   0 if the connection was successful, -1 in case of connection error
+ *
  * Note:
  *   When building a connection to the server, memory for the transmission is
  *   created as well.
@@ -125,11 +118,12 @@ void        kiro_client_free                (KiroClient *client);
 int         kiro_client_connect             (KiroClient *client, const char *dest_addr, const char *dest_port);
 
 /**
- * kiro_client_disconnect - Diconnect a #KiroClient from the Server
+ * kiro_client_disconnect:
  * @client: (transfer none): The #KiroClient to disconnect
- * Description:
+ *
  *   Disconnects the given #KiroClient from the KIRO server that it is connected
  *   to. If the @client is not connected, this function has no effect.
+ *
  * Note:
  *   The memory content that has been transfered from the server is
  *   automatically freed when calling this function. If you want to continue
@@ -142,14 +136,15 @@ int         kiro_client_connect             (KiroClient *client, const char *des
 void        kiro_client_disconnect             (KiroClient *client);
 
 /**
- * kiro_client_sync - Read data from the connected server
+ * kiro_client_sync:
  * @client: (transfer none): The #KiroServer to use sync on
- * Returns:
- *   0 if successful, -1 in case of synchronisation error
- * Description:
+ *
  *   This synchronizes the client with the server, clining the memory
  *   provided by the server to the local client. The memory can be accessed by
  *   using kiro_client_get_memory().
+ *
+ * Returns:
+ *   0 if successful, -1 in case of synchronisation error
  * Note:
  *   The server can send a 'reallocation' request to the client, forcing it to
  *   reallocate new memory freeing the old memory in the process. This might
@@ -160,19 +155,20 @@ void        kiro_client_disconnect             (KiroClient *client);
 int         kiro_client_sync                (KiroClient *client);
 
 /**
- * kiro_client_sync_partial - Read data from the connected server
+ * kiro_client_sync_partial:
  * @client: (transfer none): The #KiroServer to use sync on
  * @remote_offset: remote read offset in bytes
  * @size: ammount of bytes to read. 0 for 'until end'
  * @local_offset: offset for the storage in the local buffer
- * Returns:
- *   0 if successful, -1 in case of synchronisation error
- * Description:
+ *
  *   This synchronizes the client with the server, clining the memory
  *   provided by the server to the local client. The memory can be accessed by
  *   using kiro_client_get_memory(). Uses the offset parameters to determine
  *   which memory region to read from the server and where to store the
  *   information to.
+ *
+ * Returns:
+ *   0 if successful, -1 in case of synchronisation error
  * Note:
  *   The server can send a 'reallocation' request to the client, forcing it to
  *   reallocate new memory freeing the old memory in the process. This might
@@ -183,23 +179,26 @@ int         kiro_client_sync                (KiroClient *client);
 int         kiro_client_sync_partial        (KiroClient *client, gulong remote_offset, gulong size, gulong local_offset);
 
 /**
- * kiro_client_ping_server - Sends a PING to the server
+ * kiro_client_ping_server:
  * @client: (transfer none): The #KiroServer to send the PING from
- * Returns:
- *   A #guint telling the time (in microseconds) how long it took for the
- *   connected #KiroServer to reply
- * Description:
+ *
  *   Sends a PING package to the connected #KiroServer and waits for a PONG
  *   package from that server. The time between sending the PING and receiving
  *   the PONG (in microseconds) is measured and returned by this function.
+ *
+ * Returns:
+ *   A #guint telling the time (in microseconds) how long it took for the
+ *   connected #KiroServer to reply
  */
 gint        kiro_client_ping_server         (KiroClient *client);
 
 /**
- * kiro_client_get_memory - Return a pointer to the current client memory
+ * kiro_client_get_memory:
  * @client: (transfer none): The #KiroClient to get the memory from
- * Returns: (transfer none):
- *    A pointer to the current memory of the client.
+ *
+ *    Provides a pointer to the content of the internal memory that was pulled
+ *    from the server.
+ *
  * Note:
  *    The server can instruct the client to reallocate memory on the next
  *    occurrence of kiro_client_sync(), freeing the old memory. Also, calling
@@ -209,18 +208,21 @@ gint        kiro_client_ping_server         (KiroClient *client);
  *    information from kiro_client_get_memory() and
  *    kiro_client_get_memory_size() first.
  *    The returned memory might under NO circumstances be freed by the user!
+ * Returns: (transfer none):
+ *    A pointer to the current memory of the client.
  * See also:
  *    kiro_client_get_memory_size, kiro_client_sync
  */
 void*       kiro_client_get_memory          (KiroClient *client);
 
 /**
- * kiro_client_get_memory_size - Return the client memory size in bytes
+ * kiro_client_get_memory_size:
  * @client: (transfer none): The #KiroClient to get the memory size of
+ *
+ *    Returns the size of the allocated memory of @client, in bytes.
+ *
  * Returns:
  *    The size of the given #KiroClient memory in bytes
- * Description:
- *    Returns the size of the allocated memory of @client, in bytes.
  * Note:
  *    The server can instruct the client to reallocate memroy on the next
  *    occurrence of kiro_server_sync(), freeing the old memory. This might also
diff --git a/src/kiro-rdma.h b/src/kiro-rdma.h
index c17e044..cd07f84 100644
--- a/src/kiro-rdma.h
+++ b/src/kiro-rdma.h
@@ -16,6 +16,13 @@
    Franklin St, Fifth Floor, Boston, MA 02110, USA
 */
 
+/**
+ * SECTION: kiro-rdma
+ * 
+ * KIRO toolbox for common operations with and around the
+ * RDMA Connection Manager for InfiniBand mechanisms
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <unistd.h>
@@ -26,7 +33,14 @@
 
 #include <rdma/rdma_cma.h>
 
-
+/**
+ * kiro_connection_context: (skip)
+ *
+ * Holds all necessary metainformation to indentify with an abstract Kiro
+ * Connection. This is constructed and attached to a rdma_cm_id's context
+ * pointer.
+ *
+ */
 struct kiro_connection_context {
 
     // Information and necessary structurs
@@ -48,7 +62,13 @@ struct kiro_connection_context {
 
 };
 
-
+/**
+ * kiro_ctrl_msg: (skip)
+ *
+ * Struct representing a Kiro control-flow message which is used internally by
+ * all kiro komponents to communicate with their peer(s)
+ *
+ */
 struct kiro_ctrl_msg {
 
     enum {
@@ -64,6 +84,13 @@ struct kiro_ctrl_msg {
 };
 
 
+/**
+ * kiro_rdma_mem: (skip)
+ *
+ * Container for all necessary information and data-elements that are needed to
+ * describe memory that can be managed by means of RDMA
+ *
+ */
 struct kiro_rdma_mem {
 
     void            *mem;   // Pointer to the beginning of the memory block
diff --git a/src/kiro-sb.c b/src/kiro-sb.c
index f6e9e6f..e5a6769 100644
--- a/src/kiro-sb.c
+++ b/src/kiro-sb.c
@@ -16,18 +16,7 @@
    Franklin St, Fifth Floor, Boston, MA 02110, USA
 */
 
-/**
- * SECTION: kiro-sb
- * @Short_description: KIRO 'Synchronizing Buffer'
- * @Title: KiroSb
- *
- * KiroSb implements a 'Synchronizing Buffer' that automatically keeps the local
- * memory content up to date by mirroring the remote SyncBuffers memory content
- * automatically without any required user interaction
- */
-
 #include <stdio.h>
-
 #include <stdlib.h>
 #include <string.h>
 #include <glib.h>
diff --git a/src/kiro-sb.h b/src/kiro-sb.h
index 319d6f0..0f155c3 100644
--- a/src/kiro-sb.h
+++ b/src/kiro-sb.h
@@ -53,13 +53,6 @@ struct _KiroSb {
 
 };
 
-
-/**
- * IbvConnectorInterface:
- *
- * Base interface for IbvConnectors.
- */
-
 struct _KiroSbClass {
 
     GObjectClass parent_class;
@@ -68,27 +61,25 @@ struct _KiroSbClass {
 
 
 /* GObject and GType functions */
-/**
- * kiro_sb_get_type: (skip)
- * Returns: GType of #KiroSb
- */
 GType       kiro_sb_get_type           (void);
 
 /**
- * kiro_sb_new - Creates a new #KiroSb
- * Returns: (transfer full): A pointer to a new #KiroSb
- * Description:
+ * kiro_sb_new:
+ *
  *   Creates a new #KiroSb and returns a pointer to it.
+ *
+ * Returns: (transfer full): A pointer to a new #KiroSb
  * See also:
  *   kiro_sb_free
  */
 KiroSb*    kiro_sb_new                (void);
 
 /**
- * kiro_sb_free - 'Destroys' the given #KiroSb
- * @trb: (transfer none): The #KiroSb that is to be freed
- * Description:
- *   Clears all underlying memory and frees the object memory. 
+ * kiro_sb_free:
+ * @sb: (transfer none): The #KiroSb that is to be freed
+ *
+ *   Clears all underlying memory and frees the object memory.
+ *
  * Note:
  *   The internal memory is also freed when calling this function. If you want
  *   to continue using the raw @sb memory after you call this function, you need
@@ -100,11 +91,12 @@ KiroSb*    kiro_sb_new                (void);
 void        kiro_sb_free               (KiroSb *sb);
 
 /**
- * kiro_sb_stop - Stops the #KiroSb and clears all internal memory
+ * kiro_sb_stop:
  * @sb: (transfer none): The #KiroSb to stop
- * Description:
+ *
  *   The given #KiroSb is stopped and all internal memory is cleared. It is put
  *   back into its initial state and it can be used as if it was just created
+ *
  * See also:
  *   kiro_sb_new, kiro_sb_serve, kiro_sb_clone
  */
@@ -116,13 +108,14 @@ typedef gboolean KiroContinueFlag;
 #define KIRO_CALLBACK_REMOVE FALSE
 
 /**
- * KiroSbSyncCallbackFunc - Function type for sync callbacks os a #KiroSb
+ * KiroSbSyncCallbackFunc:
  * @user_data: (transfer none): The #user_data which was provided during
  * registration of this callback
- * Returns: A #KiroContinueFlag
- * Description:
+ *
  *   Defines the type of a callback function which will be invoked every time
  *   the #KiroSb syncs new data
+ *
+ * Returns: A #KiroContinueFlag deciding whether to keep this callback alive or not
  * Note:
  *   Returning %FALSE or %KIRO_CALLBACK_REMOVE will automatically remove the callback
  *   from the internal callback list. Return %TRUE or %KIRO_CALLBACK_CONTINUE if you
@@ -133,13 +126,14 @@ typedef gboolean KiroContinueFlag;
 typedef KiroContinueFlag (*KiroSbSyncCallbackFunc)   (void *user_data);
 
 /**
- * kiro_sb_add_sync_callback - Add a sync callback to the #KiroSb
- * @sb: (tranfer none): The #KiroSb to register this callback to
- * @func: (transfer none): A function pointer to the callback function
- * Returns: The internal id of the registerd callback
- * Description:
+ * kiro_sb_add_sync_callback:
+ * @sb: (transfer none): The #KiroSb to register this callback to
+ * @callback: (transfer none) (scope call): A function pointer to the callback function
+ *
  *   Adds a callback to the passed #KiroSbSyncCallbackFunc to this #KiroSb which
  *   will be invoked every time the #KiroSb syncs new data.
+ *
+ * Returns: The internal id of the registerd callback
  * Note:
  *   The sync callbacks will only be invoked on a 'clonig' #KiroSb. All
  *   registered callbacks will be invoked in the order they were added to the
@@ -150,16 +144,17 @@ typedef KiroContinueFlag (*KiroSbSyncCallbackFunc)   (void *user_data);
 gulong    kiro_sb_add_sync_callback (KiroSb *sb, KiroSbSyncCallbackFunc callback, void *user_data);
 
 /**
- * kiro_sb_remove_sync_callback - Remove a callback from the list
+ * kiro_sb_remove_sync_callback:
  * @sb: (transfer none): The #KiroSb to remove the callback from
  * @id: The id of the callback to be removed
- * Returns: A #gboolean. %TRUE if the callback was found and removed. %FALSE
- *   otherwise
- * Description:
+ *
  *   Removes the callback with the given @id from the internal list. If the
  *   callback with the given @id was not found %FALSE is returned. If the
  *   callback with the given @id was found, it will be removed from the callback
  *   list and %TRUE is returned
+ *
+ * Returns: A #gboolean. %TRUE if the callback was found and removed. %FALSE
+ *   otherwise
  * Note:
  *   Any currently active callback will still finish before it is removed from
  *   the list.
@@ -169,10 +164,11 @@ gulong    kiro_sb_add_sync_callback (KiroSb *sb, KiroSbSyncCallbackFunc callback
 gboolean    kiro_sb_remove_sync_callback (KiroSb *sb, gulong id);
 
 /**
- * kiro_sb_clear_sync_callbacks - Clear all sync callbacks
+ * kiro_sb_clear_sync_callbacks:
  * @sb: (transfer none): The #KiroSb to perform this operation on
- * Description:
+ *
  *   Removes all registerd callbacks from the internal list
+ *
  * Note:
  *   Any currently active callbacks will still finish before they are removed
  *   from the list
@@ -182,14 +178,13 @@ gboolean    kiro_sb_remove_sync_callback (KiroSb *sb, gulong id);
 void    kiro_sb_clear_sync_callbacks (KiroSb *sb);
 
 /**
- * kiro_sb_serve - Allow remote KiroSbs to clone this buffers memory
- * Returns: A gboolean. TRUE = success. FALSE = fail.
+ * kiro_sb_serve:
  * @sb: (transfer none): The #KiroSb to perform this operation on
  * @size: Size in bytes of the content that will be served
  * @addr: Optional address parameter to define where to listen for new
  * connections.
  * @port: Optional port to listen on for new connections
- * Description:
+ *
  *   Allows other remote #KiroSbs to connect to this #KiroSb and clone its
  *   memory. The internal memory is initially empty. Use the kiro_sb_push or
  *   kiro_sb_push_dma functions to update the served data.
@@ -198,6 +193,8 @@ void    kiro_sb_clear_sync_callbacks (KiroSb *sb);
  *   the first device it can find. If @port is given, the #KiroSb will listen
  *   for new connections on this specific port. Otherwise, the default port
  *   '60010' will be used.
+ *
+ * Returns: A gboolean. TRUE = success. FALSE = fail.
  * Note:
  *   A #KiroSb that already 'serves' its content can no longer clone
  *   other remote #KiroSbs.
@@ -207,14 +204,15 @@ void    kiro_sb_clear_sync_callbacks (KiroSb *sb);
 gboolean    kiro_sb_serve           (KiroSb *sb, gulong size, const gchar *addr, const gchar *port);
 
 /**
- * kiro_sb_clone - Clone the content of a remote #KiroSb
- * Returns: A gboolean. TRUE = connection successful. FALSE = connection failed.
+ * kiro_sb_clone:
  * @sb: (transfer none): The #KiroSb to perform this operation on
  * @address: The InfiniBand address of the remote #KiroSb which should be cloned
  * @port: The InfiniBand port of the remote #KiroSb which should be cloned
- * Description:
+ *
  *   Connects to the remote #KiroSb given by @address and @port and
  *   continuousely clones its content into the local #KiroSb
+ *
+ * Returns: A gboolean. TRUE = connection successful. FALSE = connection failed.
  * Note:
  *   A #KiroSb that clones a remote #KiroSb can no longer start to 'serve' its
  *   content to other remote #KiroSbs
@@ -224,12 +222,13 @@ gboolean    kiro_sb_serve           (KiroSb *sb, gulong size, const gchar *addr,
 gboolean    kiro_sb_clone       (KiroSb *sb, const gchar *address, const gchar *port);
 
 /**
- * kiro_sb_get_size - Get the size in bytes of the managed memory
- * Returns: A gulong giving the size of the managed memory in bytes
+ * kiro_sb_get_size:
  * @sb: (transfer none): The #KiroSb to perform this operation on
- * Description:
+ *
  *   Returns the size in bytes of the content that is being served and/or cloned
  *   from.
+ *
+ * Returns: A gulong giving the size of the managed memory in bytes
  * Note:
  *   Since #KiroSb uses an internal triple buffer, the value gained from this
  *   function only gives the size of one element from that buffer. The size of
@@ -240,33 +239,36 @@ gboolean    kiro_sb_clone       (KiroSb *sb, const gchar *address, const gchar *
 gulong      kiro_sb_get_size    (KiroSb *sb);
 
 /**
- * kiro_sb_freeze - Stop auto syncing
+ * kiro_sb_freeze:
  * @sb: (transfer none): The #KiroSb to perform this operation on
- * Description:
+ *
  *   Stops the given #KiroSb from automatically syncing.
+ *
  * See also:
  *   kiro_sb_thaw
  */
 void      kiro_sb_freeze      (KiroSb *sb);
 
 /**
- * kiro_sb_thaw - Enable auto syncing
+ * kiro_sb_thaw:
  * @sb: (transfer none): The #KiroSb to perform this operation on
- * Description:
+ *
  *   Enable the given #KiroSb automatic syncing.
+ *
  * See also:
  *   kiro_sb_freeze
  */
 void     kiro_sb_thaw         (KiroSb *sb);
 
 /**
- * kiro_sb_get_data - Get a pointer to the stored data
+ * kiro_sb_get_data:
  * @sb: (transfer none) The #KiroSb to get the data from
- * Returns: A void pointer the stored data
- * Description:
+ *
  *   Returns a void pointer to the most current incarnation of the stored data.
  *   Data might either change by pushing (in case of a 'serving' #KiroSb) or
  *   after (automatic or manual) syncing (in case of a 'cloning' #KiroSb).
+ *
+ * Returns: (transfer none): A void pointer the stored data
  * Note:
  *   The returned pointer to the element might become invalid at any time by
  *   automatic or manual sync. Under no circumstances might the returned pointer
@@ -279,12 +281,13 @@ void     kiro_sb_thaw         (KiroSb *sb);
 void*   kiro_sb_get_data     (KiroSb *sb);
 
 /**
- * kiro_sb_get_data_blocking - Wait for new data and return a pointer to it
+ * kiro_sb_get_data_blocking:
  * @sb: (transfer none) The #KiroSb to get the data from
- * Returns: A void pointer the stored data
- * Description:
+ *
  *   Calling this function will do the same thing as kiro_sb_get_data, but it
  *   will internaly wait until new data has arived before returning it.
+ *
+ * Returns: (transfer none): A void pointer the stored data
  * Note:
  *   The returned pointer to the element might become invalid at any time by
  *   automatic or manual sync. Under no circumstances might the returned pointer
@@ -297,30 +300,32 @@ void*   kiro_sb_get_data     (KiroSb *sb);
 void*   kiro_sb_get_data_blocking  (KiroSb *sb);
 
 /**
- * kiro_sb_push - Push data into the memory
+ * kiro_sb_push:
  * @sb: (transfer none) The #KiroSb to get the data from
  * @data: (transfer none) void pointer to copy data from
- * Returns: %TRUE on success %FALSE in case of error
- * Desciption:
+ *
  *   Updates the internal memory by memcopy()-ing the given element into it.
  *   This operation is only valid for 'serving' #KiroSb. Calling this function
  *   on a 'cloning' #KiroSb will allways return %FALSE.
+ *
+ * Returns: %TRUE on success %FALSE in case of error
  * Note:
  *   The internal memcopy() will assume an element of the correct size (given
- *   with the initial call to kiro_sb_serve or returned by kiro_sb_get_size) 
+ *   with the initial call to kiro_sb_serve or returned by kiro_sb_get_size)
  * See also:
  *   kiro_sb_get_size, kiro_sb_serve
  */
 gboolean kiro_sb_push       (KiroSb *sb, void *data);
 
 /**
- * kiro_sb_push_dma - Push data into the memory using memory access
+ * kiro_sb_push_dma:
  * @sb: (transfer none) The #KiroSb to get the data from
- * Returns: A pointer to the memory where the new data should be stored
- * Desciption:
+ *
  *   Returns a pointer where the new data should be stored.
  *   This operation is only valid for a 'serving' #KiroSb. Calling this
  *   function on a 'cloning' #KiroSb will allways return a %NULL pointer.
+ *
+ * Returns: (transfer none): A pointer to the memory where the new data should be stored
  * Note:
  *   It is the users responsibility to ensure no more data is written to the
  *   pointed memory then was specified with the initial call to kiro_sb_serve or
diff --git a/src/kiro-server.c b/src/kiro-server.c
index f8dd9d3..041814d 100644
--- a/src/kiro-server.c
+++ b/src/kiro-server.c
@@ -16,15 +16,6 @@
    Franklin St, Fifth Floor, Boston, MA 02110, USA
 */
 
-/**
- * SECTION: kiro-server
- * @Short_description: KIRO RDMA Server / Consumer
- * @Title: KiroServer
- *
- * KiroServer implements the server / passive / provider side of the the RDMA
- * Communication Channel. It uses a KIRO-TRB to manage its data.
- */
-
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
diff --git a/src/kiro-server.h b/src/kiro-server.h
index 655140a..8479e15 100644
--- a/src/kiro-server.h
+++ b/src/kiro-server.h
@@ -54,13 +54,6 @@ struct _KiroServer {
     KiroServerPrivate *priv;
 };
 
-
-/**
- * IbvConnectorInterface:
- *
- * Base interface for IbvConnectors.
- */
-
 struct _KiroServerClass {
 
     GObjectClass parent_class;
@@ -70,29 +63,26 @@ struct _KiroServerClass {
 
 
 /* GObject and GType functions */
-
-/**
- * kiro_server_get_type: (skip)
- * Returns: GType of KiroServer
- */
 GType        kiro_server_get_type            (void);
 
 /**
- * kiro_server_new - Creates a new #KiroServer
+ * kiro_server_new:
+ * Creates a new, unbound #KiroServer and returns a pointer to it.
+ *
  * Returns: (transfer full): A pointer to a new #KiroServer
- * Description:
- *   Creates a new, unbound #KiroServer and returns a pointer to it.
+ *
  * See also:
  *   kiro_server_start, kiro_server_free
  */
 KiroServer*  kiro_server_new                (void);
 
 /**
- * kiro_server_free - 'Destroys' the given #KiroServer
+ * kiro_server_free:
  * @server: The #KiroServer that is to be freed
- * Description:
+ *
  *   Transitions the #KiroServer through all necessary shutdown routines and
  *   frees the object memory.
+ *
  * Note:
  *   The memory that is given to the server when calling kiro_server_start will
  *   NOT be freed! The user is responsible to free this memory, if no longer
@@ -106,15 +96,16 @@ void         kiro_server_free                (KiroServer *server);
 /* server functions */
 
 /**
- * kiro_server_start - Starts the server, providing the given memory
+ * kiro_server_start:
  * @server: #KiroServer to perform the operation on
  * @bind_addr: Local address to bind the server to
  * @bind_port: Local port to listen for connections
  * @mem: (transfer none): Pointer to the memory that is to be provided
  * @mem_size: Size in bytes of the given memory
- * Description:
+ *
  *   Starts the #KiroServer to provide the given memory to any connecting
  *   client.
+ *
  * Notes:
  *   If the bind_addr is NULL, the server will bind to the first device
  *   it can find on the machine and listen across all IPs. Otherwise it
@@ -131,22 +122,23 @@ int kiro_server_start (KiroServer *server, const char *bind_addr, const char *bi
 
 
 /**
- * kiro_server_realloc - Change the memory that is provided by the server
+ * kiro_server_realloc:
  * @server: #KiroServer to perform the operation on
  * @mem: (transfer none): Pointer to the memory that is to be provided
  * @mem_size: Size in bytes of the given memory
- * Description:
+ *
  *   Changes the memory that is provided by the server. All connected clients
  *   will automatically be informed about this change.
  */
-void kiro_server_realloc (KiroServer *self, void* mem, size_t mem_size);
+void kiro_server_realloc (KiroServer *server, void* mem, size_t mem_size);
 
 
 /**
- * kiro_server_stop - Stops the server
+ * kiro_server_stop:
  * @server: #KiroServer to perform the operation on
- * Description:
+ *
  *   Stops the given #KiroServer
+ *
  * See also:
  *   kiro_server_start
  */
diff --git a/src/kiro-trb.c b/src/kiro-trb.c
index c3ed968..97ca047 100644
--- a/src/kiro-trb.c
+++ b/src/kiro-trb.c
@@ -16,18 +16,7 @@
    Franklin St, Fifth Floor, Boston, MA 02110, USA
 */
 
-/**
- * SECTION: kiro-trb
- * @Short_description: KIRO 'Transmittable Ring Buffer'
- * @Title: KiroTrb
- *
- * KiroTrb implements a 'Transmittable Ring Buffer' that holds all necessary information
- * about its content inside itself, so its data can be exchanged between different
- * instances of the KiroTrb Class and/or sent over a network.
- */
-
 #include <stdio.h>
-
 #include <stdlib.h>
 #include <string.h>
 #include <glib.h>
diff --git a/src/kiro-trb.h b/src/kiro-trb.h
index bec8626..3549a1d 100644
--- a/src/kiro-trb.h
+++ b/src/kiro-trb.h
@@ -53,13 +53,6 @@ struct _KiroTrb {
 
 };
 
-
-/**
- * IbvConnectorInterface:
- *
- * Base interface for IbvConnectors.
- */
-
 struct _KiroTrbClass {
 
     GObjectClass parent_class;
@@ -78,32 +71,30 @@ struct KiroTrbInfo {
 
 
 /* GObject and GType functions */
-/**
- * kiro_trb_get_type: (skip)
- * Returns: GType of #KiroTrb
- */
 GType       kiro_trb_get_type           (void);
 
 /**
- * kiro_trb_new - Creates a new #KiroTrb
- * Returns: (transfer full): A pointer to a new #KiroTrb
- * Description:
+ * kiro_trb_new:
+ *
  *   Creates a new, unshaped #KiroTrb and returns a pointer to it.
+ *
+ * Returns: (transfer full): A pointer to a new #KiroTrb
  * See also:
  *   kiro_trb_free, kiro_trb_reshape
  */
 KiroTrb*    kiro_trb_new                (void);
 
 /**
- * kiro_trb_free - 'Destroys' the given #KiroTrb
+ * kiro_trb_free:
  * @trb: (transfer none): The #KiroTrb that is to be freed
- * Description:
- *   Clears all underlying memory and frees the object memory. 
+ *
+ *   Clears all underlying memory and frees the object memory.
+ *
  * Note:
  *   The internal memory is also freed when calling this function. If you want
  *   to continue using the raw @trb memory after call this function, you need to
  *   memcpy() its content using the information optained from
- *   kiro_trb_get_raw_buffer and kiro_trb_get_raw_size. 
+ *   kiro_trb_get_raw_buffer and kiro_trb_get_raw_size.
  * See also:
  *   kiro_trb_new
  */
@@ -114,10 +105,10 @@ void        kiro_trb_free               (KiroTrb *trb);
 
 /**
  * kiro_trb_get_element_size:
- * Returns the element size in bytes
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
  *   Returns the size of the individual elements in the buffer
+ *
  * See also:
  *   kiro_trb_reshape, kiro_trb_adopt, kiro_trb_clone
  */
@@ -125,11 +116,11 @@ uint64_t kiro_trb_get_element_size (KiroTrb *trb);
 
 /**
  * kiro_trb_get_max_elements:
- * Returns the capacity of the buffer
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
  *   Returns the mximal number of elements that can be stored in
  *   the buffer
+ *
  * See also:
  *   kiro_trb_get_element_size, kiro_trb_reshape, kiro_trb_adopt,
  *   kiro_trb_clone
@@ -139,10 +130,10 @@ uint64_t kiro_trb_get_max_elements (KiroTrb *trb);
 
 /**
  * kiro_trb_get_raw_size:
- * Returns the size of the buffer memory
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
  *   Returns the size of the buffers internal memory
+ *
  * Notes:
  *   The returned size is given INCLUDING the header on top of the
  *   buffers internal memory
@@ -155,9 +146,10 @@ uint64_t kiro_trb_get_raw_size (KiroTrb *trb);
 
 /**
  * kiro_trb_get_raw_buffer:
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
  *   Returns a pointer to the memory structure of the given buffer.
+ *
  * Returns: (transfer none): a pointer to the buffer memory
  * Notes:
  *   The returned pointer points to the beginning of the internal
@@ -180,10 +172,11 @@ void* kiro_trb_get_raw_buffer (KiroTrb *trb);
 
 /**
  * kiro_trb_get_element:
- * @trb: #KiroTrb to perform the operation on
+ * @trb: (transfer none): #KiroTrb to perform the operation on
  * @index: Index of the element in the buffer to access
- * Description:
+ *
  *   Returns a pointer to the element in the buffer at the given index.
+ *
  * Returns: (transfer none): a pointer to the element at the given index.
  * Notes:
  *   The returned pointer to the element is only guaranteed to be valid
@@ -204,12 +197,12 @@ void* kiro_trb_get_element (KiroTrb *trb, glong index);
 
 /**
  * kiro_trb_dma_push:
- * Gives DMA to the next element and pushes the buffer
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
  *   Returns a pointer to the next element in the buffer and increases
  *   all internal counters and meta data as if an element was pushed
  *   onto the buffer.
+ *
  * Returns: (transfer none): Pointer to the bginning of element memory
  * Notes:
  *   The returned pointer to the element is only guaranteed to be valid
@@ -230,10 +223,10 @@ void* kiro_trb_dma_push (KiroTrb *trb);
 
 /**
  * kiro_trb_flush:
- * Flushes the buffer
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
  *   Flushes the internal buffer so the buffer is 'empty' again.
+ *
  * Notes:
  *   The underlying memory is not cleared, freed or rewritten.
  *   Only the header is rewritten and the internal pointer and
@@ -247,12 +240,12 @@ void kiro_trb_flush (KiroTrb *trb);
 /**
  * kiro_trb_purge:
  * Completely resets the Buffer
- * @trb: #KiroTrb to perform the operation on
- * @free_memory: True = internal memory will be free()'d,
- *               False = internal memory will be 'orphaned'
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ * @free_memory: Decides how to treat intermal memory on purge
+ *
  *   Resets all internal structures so the TRB becomes
  *   'uninitialized' again.
+ *
  * Notes:
  *   Depending on the 'free_memory' argument, any currently
  *   held internal memory either gets free()'d or is simply
@@ -265,11 +258,11 @@ void kiro_trb_purge (KiroTrb *trb, gboolean free_memory);
 
 /**
  * kiro_trb_is_setup:
- * Returns the setup status of the buffer
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
  *   Returns an integer designating of the buffer is ready to
  *   be used or needs to be 'reshaped' before it can accept data
+ *
  * Notes:
  *   A return value of 0 designates that the buffer is not ready
  *   to be used. Values greater than 0 designate that the buffer
@@ -282,15 +275,15 @@ int kiro_trb_is_setup (KiroTrb *trb);
 
 /**
  * kiro_trb_reshape:
- * Reallocates internal memory and structures
- * @trb: #KiroTrb to perform the operation on
+ * @trb: (transfer none): #KiroTrb to perform the operation on
  * @element_size: Individual size of the elements to store in bytes
  * @element_count: Maximum number of elements to be stored
- * Returns:
- *   integer: < 0 for error, >= 0 for success
- * Description:
+ *
  *   (Re)Allocates internal memory for the given ammount of elements
  *   at the given individual size
+ *
+ * Returns:
+ *   integer: < 0 for error, >= 0 for success
  * Notes:
  *   If this function gets called when the buffer already has internal
  *   memory (buffer is setup), that memory gets freed automatically.
@@ -304,12 +297,12 @@ int kiro_trb_reshape (KiroTrb *trb, uint64_t element_size, uint64_t element_coun
 
 /**
  * kiro_trb_clone:
- * Clones the given memory into the internal memory
- * @trb: #KiroTrb to perform the operation on
+ * @trb: (transfer none); #KiroTrb to perform the operation on
  * @source: Pointer to the source memory to clone from
- * Description:
+ *
  *   Interprets the given memory as a pointer to another KIRO TRB and
  *   tries to copy that memory into its own.
+ *
  * Notes:
  *   The given memory is treated as a correct KIRO TRB memory block,
  *   including a consistent memory header. That header is read and
@@ -327,11 +320,11 @@ int kiro_trb_clone (KiroTrb *trb, void *source);
 
 /**
  * kiro_trb_push:
- * Adds an element into the buffer
- * @trb: #KiroTrb to perform the operation on
+ * @trb: (transfer none): #KiroTrb to perform the operation on
  * @source: Pointer to the memory of the element to add
- * Description:
+ *
  *   Copies the given element and adds it into the buffer
+ *
  * Notes:
  *   This function will read n-Bytes from the given address according
  *   to the setup element_size. The read memory is copied directly
@@ -348,11 +341,11 @@ int kiro_trb_push (KiroTrb *trb, void *source);
 
 /**
  * kiro_trb_refresh:
- * Re-reads the TRBs memory header
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
  *   Re-reads the internal memory header and sets up all pointers
  *   and counters in accordance to these information
+ *
  * Notes:
  *   This function is used in case the TRBs memory got changed
  *   directly (For example, by a DMA operation) to make the TRB
@@ -367,12 +360,12 @@ void kiro_trb_refresh (KiroTrb *trb);
 
 /**
  * kiro_trb_adopt:
- * Adopts the given memory into the TRB
- * @trb: #KiroTrb to perform the operation on
+ * @trb: (transfer none): #KiroTrb to perform the operation on
  * @source: Pointer to the source memory to adopt
- * Description:
+ *
  *   Interprets the given memory as a pointer to another KIRO TRB and
  *   takes ownership over the memory.
+ *
  * Notes:
  *   The given memory is treated as a correct KIRO TRB memory block,
  *   including a consistent memory header. That header is read and