Improve doxygen comments in client header

[Bug/Feature]  N/A
[Cause]        N/A
[Solution]     * more details added
               * example code provided.
[Verification] Run generate_documentation.sh script, verify output.
               Non-comment parts hasn't been affected.

Change-Id: I506913c3047f64f64f1ff2e84c92cff9fda8b43f

diff --git a/client/security-containers-client.h b/client/security-containers-client.h
index 1632497..c56e9de 100644 (file)
--- a/client/security-containers-client.h
+++ b/client/security-containers-client.h
@@ -21,6 +21,58 @@
  * @file
  * @author  Mateusz Malicki (m.malicki2@samsung.com)
  * @brief   This file contains the public API for Security Containers Client
+ *
+ * @par Example usage:
+ * @code
+#include <stdio.h>
+#include "client/security-containers-client.h"
+
+int main(int argc, char** argv)
+{
+    ScStatus status;
+    ScClient client;
+    ScArrayString values = NULL;
+    int ret = 0;
+
+    status = sc_start_glib_loop(); // start glib loop (if not started any yet)
+    if (SCCLIENT_SUCCESS != status) {
+        // error!
+        return 1;
+    }
+
+    client = sc_client_create(); // create client handle
+    if (NULL == client) {
+        // error!
+        ret = 1;
+        goto finish;
+    }
+
+    status = sc_connect(client); // connect to dbus
+    if (SCCLIENT_SUCCESS != status) {
+        // error!
+        ret = 1;
+        goto finish;
+    }
+
+    status = sc_get_container_ids(client, &values);
+    if (SCCLIENT_SUCCESS != status) {
+        // error!
+        ret = 1;
+        goto finish;
+    }
+
+    // print array
+    for (ScArrayString iValues = values; *iValues; iValues++) {
+        printf("%s\n", *iValues);
+    }
+
+finish:
+    sc_array_string_free(values); // free memory
+    sc_client_free(client); // destroy client handle
+    sc_stop_glib_loop(); // stop the glib loop (use only with sc_start_glib_loop)
+    return ret;
+}
+ @endcode
  */
 
 #ifndef SECURITY_CONTAINERS_CLIENT_H
@@ -32,21 +84,21 @@ extern "C"
 #endif
 
 /**
- * security-containers-server's client
+ * security-containers-server's client pointer.
  */
 typedef void* ScClient;
 
 /**
- * String type.
+ * NULL-terminated string type.
  *
- * NULL-terminated string.
+ * @sa sc_array_string_free
  */
 typedef char* ScString;
 
 /**
- * Array of strings type.
+ * NULL-terminated array of strings type.
  *
- * Array are NULL-terminated.
+ * @sa sc_string_free
  */
 typedef ScString* ScArrayString;
 
@@ -65,8 +117,8 @@ typedef enum {
 /**
  * Start glib loop.
  *
- * Do not call this function if the application creates glib loop itself.
- * Otherwise call it before any other function from this library.
+ * Do not call this function if an application creates a glib loop itself.
+ * Otherwise, call it before any other function from this library.
  *
  * @return status of this function call
  */
@@ -75,6 +127,8 @@ ScStatus sc_start_glib_loop();
 /**
  * Stop glib loop.
  *
+ * Call only if sc_start_glib_loop() was called.
+ *
  * @return status of this function call
  */
 ScStatus sc_stop_glib_loop();
@@ -82,21 +136,21 @@ ScStatus sc_stop_glib_loop();
 /**
  * Create a new security-containers-server's client.
  *
- * @return created client
+ * @return Created client pointer or NULL on failure.
  */
 ScClient sc_client_create();
 
 /**
  * Release client resources.
  *
- * @param client security-containers-server's client
+ * @param[in] client security-containers-server's client
  */
 void sc_client_free(ScClient client);
 
 /**
  * Get status code of last security-containers-server communication.
  *
- * @param client security-containers-server's client
+ * @param[in] client security-containers-server's client
  * @return status of this function call
  */
 ScStatus sc_get_status(ScClient client);
@@ -104,7 +158,7 @@ ScStatus sc_get_status(ScClient client);
 /**
  * Get status message of the last security-containers-server communication.
  *
- * @param client security-containers-server's client
+ * @param[in] client security-containers-server's client
  * @return last status message from security-containers-server communication
  */
 const char* sc_get_status_message(ScClient client);
@@ -112,7 +166,7 @@ const char* sc_get_status_message(ScClient client);
 /**
  * Connect client to the security-containers-server.
  *
- * @param client security-containers-server's client
+ * @param[in] client security-containers-server's client
  * @return status of this function call
  */
 ScStatus sc_connect(ScClient client);
@@ -120,8 +174,8 @@ ScStatus sc_connect(ScClient client);
 /**
  * Connect client to the security-containers-server via custom address.
  *
- * @param client security-containers-server's client
- * @param address dbus address
+ * @param[in] client security-containers-server's client
+ * @param[in] address dbus address
  * @return status of this function call
  */
 ScStatus sc_connect_custom(ScClient client, const char* address);
@@ -129,7 +183,7 @@ ScStatus sc_connect_custom(ScClient client, const char* address);
 /**
  * Release ScArrayString.
  *
- * @param astring ScArrayString
+ * @param[in] astring ScArrayString
  */
 void sc_array_string_free(ScArrayString astring);
 
@@ -141,14 +195,20 @@ void sc_array_string_free(ScArrayString astring);
 void sc_string_free(ScString string);
 
 
-/*************************************************************************************************
+/**
+ * @name Host API
  *
- *  org.tizen.containers.host.manager interface
+ * Functions using org.tizen.containers.host.manager D-Bus interface.
  *
- ************************************************************************************************/
+ * @{
+ */
 
 /**
- * Dbus state change callback function signature.
+ * Container's D-Bus state change callback function signature.
+ *
+ * @param[in] containerId affected container id
+ * @param[in] dbusAddress new D-Bus address
+ * @param data custom user's data pointer passed to sc_container_dbus_state() function
  */
 typedef void (*ScContainerDbusStateCallback)(const char* containerId,
                                              const char* dbusAddress,
@@ -162,6 +222,7 @@ typedef void (*ScContainerDbusStateCallback)(const char* containerId,
  * @param[out] values array of containers dbus address
  * @return status of this function call
  * @post keys[i] corresponds to values[i]
+ * @remark Use sc_array_string_free() to free memory occupied by @p keys and @p values.
  */
 ScStatus sc_get_container_dbuses(ScClient client, ScArrayString* keys, ScArrayString* values);
 
@@ -171,23 +232,25 @@ ScStatus sc_get_container_dbuses(ScClient client, ScArrayString* keys, ScArraySt
  * @param[in] client security-containers-server's client
  * @param[out] array array of containers name
  * @return status of this function call
+ * @remark Use sc_array_string_free() to free memory occupied by @p array.
  */
 ScStatus sc_get_container_ids(ScClient client, ScArrayString* array);
 
 /**
- * Get active container name.
+ * Get active (foreground) container name.
  *
  * @param[in] client security-containers-server's client
  * @param[out] id active container name
  * @return status of this function call
+ * @remark Use @p sc_string_free() to free memory occupied by @p id.
  */
 ScStatus sc_get_active_container_id(ScClient client, ScString* id);
 
 /**
- * Set active container.
+ * Set active (foreground) container.
  *
- * @param client security-containers-server's client
- * @param id container name
+ * @param[in] client security-containers-server's client
+ * @param[in] id container name
  * @return status of this function call
  */
 ScStatus sc_set_active_container(ScClient client, const char* id);
@@ -195,26 +258,35 @@ ScStatus sc_set_active_container(ScClient client, const char* id);
 /**
  * Register dbus state change callback function.
  *
- * The callback function will be invoked on a different thread
+ * @note The callback function will be invoked on a different thread.
  *
- * @param client security-containers-server's client
- * @param containerDbusStateCallback callback function
- * @param data some extra data that will be passed to callback function
+ * @param[in] client security-containers-server's client
+ * @param[in] containerDbusStateCallback callback function
+ * @param[in] data some extra data that will be passed to callback function
  * @return status of this function call
  */
 ScStatus sc_container_dbus_state(ScClient client,
                                  ScContainerDbusStateCallback containerDbusStateCallback,
                                  void* data);
 
+/** @} */ // Host API
+
 
-/*************************************************************************************************
+/**
+ * @name Domain API
  *
- *  org.tizen.containers.domain.manager interface
+ * Functions using org.tizen.containers.domain.manager D-Bus interface.
  *
- ************************************************************************************************/
+ * @{
+ */
 
 /**
  * Notification callback function signature.
+ *
+ * @param[in] container source container
+ * @param[in] application sending application name
+ * @param[in] message notification message
+ * @param data custom user's data pointer passed to sc_notification()
  */
 typedef void (*ScNotificationCallback)(const char* container,
                                        const char* application,
@@ -223,9 +295,9 @@ typedef void (*ScNotificationCallback)(const char* container,
 /**
  * Send message to active container.
  *
- * @param client security-containers-server's client
- * @param application application name
- * @param message message
+ * @param[in] client security-containers-server's client
+ * @param[in] application application name
+ * @param[in] message message
  * @return status of this function call
  */
 ScStatus sc_notify_active_container(ScClient client, const char* application, const char* message);
@@ -233,23 +305,27 @@ ScStatus sc_notify_active_container(ScClient client, const char* application, co
 /**
  * Move file between containers.
  *
- * @param client security-containers-server's client
- * @param destContainer destination container id
- * @param path path to moved file
+ * @param[in] client security-containers-server's client
+ * @param[in] destContainer destination container id
+ * @param[in] path path to moved file
+ * @return status of this function call
  */
 ScStatus sc_file_move_request(ScClient client, const char* destContainer, const char* path);
 
 /**
  * Register notification callback function.
  *
- * The callback function will be invoked on a different thread.
+ * @note The callback function will be invoked on a different thread.
  *
- * @param client security-containers-server's client
- * @param notificationCallback callback function
- * @param data some extra data that will be passed to callback function
+ * @param[in] client security-containers-server's client
+ * @param[in] notificationCallback callback function
+ * @param[in] data some extra data that will be passed to callback function
  * @return status of this function call
  */
 ScStatus sc_notification(ScClient client, ScNotificationCallback notificationCallback, void* data);
+
+/** @} */ // Domain API
+
 #ifdef __cplusplus
 }
 #endif