Further code review

git-svn-id: file:///svnroot/mdictionary/trunk@225 5bde0345-f819-0410-ac75-e5045f9217cc

diff --git a/src/dbus_wrapper/Doxyfile b/src/dbus_wrapper/Doxyfile
index 27787aa..088aed7 100644 (file)
--- a/src/dbus_wrapper/Doxyfile
+++ b/src/dbus_wrapper/Doxyfile
@@ -459,7 +459,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
  
-INPUT                  = ../../include/ws_dbus.h
+INPUT                  = ../../include/ws_dbus.h src/ws_dbus.c
  
 # If the value of the INPUT tag contains directories, you can use the 
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 

diff --git a/src/dbus_wrapper/src/ws_dbus.c b/src/dbus_wrapper/src/ws_dbus.c
index 7d40aae..79d71f3 100644 (file)
--- a/src/dbus_wrapper/src/ws_dbus.c
+++ b/src/dbus_wrapper/src/ws_dbus.c
@@ -47,6 +47,9 @@ static gchar* ws_dbus_get_ptr2method (GArray *methods, gchar* name );
 static void ws_dbus_libosso_errors (osso_return_t result);
 static void ws_dbus_fill_message (DBusMessage *msg, void *data);
 
+/**This function will be used in future version of DBUS as soon as introspection
+ * is implemented
+ */
 static gchar* ws_dbus_get_ptr2method (GArray *methods, gchar* name)
 {
        guint i;
@@ -153,7 +156,9 @@ static gint ws_dbus_cb_handler (const gchar * interface,
        temp = g_quark_try_string (method); 
        if (temp != 0)
        {
-               //run through all available methods and run the one which was called remotely
+               /*run through all available methods and run the one which was 
+               called remotely*/
+
                for (i=0; i < dbus_method_data->len; ++i)
                {
                        method_data = g_array_index( dbus_method_data,
@@ -180,7 +185,10 @@ static gint ws_dbus_cb_handler (const gchar * interface,
 };
 
 
-/* This function adds words stored in a GArray as arguments to a DBUS message */
+/** This function adds words stored in a GArray as arguments to a DBUS message 
+ * \param msg - DBusMessage structure
+ * \param data - GArray of osso_rpc_t containing arguments and its types
+ */
 static void ws_dbus_fill_message (DBusMessage *msg, void *data) 
 {
        guint i;
@@ -240,6 +248,12 @@ static void ws_dbus_fill_message (DBusMessage *msg, void *data)
        g_debug ("DBUS: Added %d words\n", i);
 };
 
+/**Function will be used in future version of dbus wrapper library, as soon as
+ *introspection is implemented
+ *\param error - a GError error
+ *\param data - a GArray of methods (listed in a string form)
+ *\param user_data - a pointer WSDBusData structure
+*/
 void ws_dbus_add_remote_methods (GError *error,
                                  gpointer data,
                                  gpointer user_data)
@@ -260,6 +274,13 @@ void ws_dbus_add_remote_methods (GError *error,
        return;
 };
 
+/** This function is used for allocating memory for the WSDBusData structure and 
+ * setting some basic parameters. 
+ * \param name - name of the application
+ * \param version - app's version
+ * \return pointer to WSDBusData structure\n
+ * \sa WSDBusData
+ */
 WSDBusData * ws_dbus_create (gchar *name, gchar *version)
 {
        WSDBusData *temp;
@@ -286,7 +307,16 @@ WSDBusData * ws_dbus_create (gchar *name, gchar *version)
        return temp;
 };
 
-/* Set destination and source addresses of DBUS communication */
+/** Setting DBUS wrapper configuration.
+ * \param ws_dbus_data - pointer to a structure uniquely identifying 
+ * the application for DBus. The possible values of 
+ * this parameter are listed here: ::WSDBusConfig
+ * \param field - the name of the variable, this function is supposed to set. 
+ * \param value - the value of the variable
+ * \return WS_STATUS_OK - on success \n
+ * WS_STATUS_ERROR - on error
+ * \sa WSDBusConfig
+ */
 WSDBusStatus ws_dbus_config (WSDBusData * ws_dbus_data,
                              WSDBusConfig field,
                              gchar *value)
@@ -323,6 +353,16 @@ WSDBusStatus ws_dbus_config (WSDBusData * ws_dbus_data,
        return WS_DBUS_STATUS_OK;
 };
 
+/** It should be the called after <B>ws_dbus_create</B> and after setting all 
+ * DBUS parameters with the <B>ws_dbus_config</B> function.
+ * The structure it returns is necessary to call every function implemented in
+ * this wrapper library.
+ * \param ws_dbus_data - it's a structure containing the unique paths to objects 
+ * and interfaces to be registered in the DBus session daemon
+ * \return WS_STATUS_OK - on success \n
+ * WS_STATUS_ERROR - on error
+ * \sa WSDBusConfig | ws_dbus_create | ws_dbus_config
+ */
 WSDBusStatus ws_dbus_connect (WSDBusData * ws_dbus_data)
 {
        osso_return_t result;
@@ -356,7 +396,12 @@ WSDBusStatus ws_dbus_connect (WSDBusData * ws_dbus_data)
        }
 };
 
-/* Free allocated memory */
+/** Before the program exits, all memory allocated by DBUS wrapper should be 
+ * freed.
+ * \param ws_dbus_data - pointer to a structure uniquely identifying the 
+ * application for DBus
+ * \return \li WS_STATUS_OK - on success \li WS_STATUS_ERROR - on error
+ */
 void ws_dbus_destroy (WSDBusData * ws_dbus_data)
 {
        guint i;
@@ -399,10 +444,9 @@ void ws_dbus_destroy (WSDBusData * ws_dbus_data)
        g_free (ws_dbus_data->remote_object);
        g_free (ws_dbus_data->remote_iface);
        
-       /** \TODO is this needed still? */
-       /* Introspection not implemented yet - IS IT NEEDED?? */
-       /*
-        * if (ws_dbus_data->remote_method_data != NULL) 
+       /* Introspection not implemented yet. This piece of code will be used 
+        *in future version.*/
+       /* if (ws_dbus_data->remote_method_data != NULL) 
         * {
         *      for (i = 0; i < ws_dbus_data->remote_method_data->len; ++i)
         *      {
@@ -410,13 +454,24 @@ void ws_dbus_destroy (WSDBusData * ws_dbus_data)
         *                      gchar*, i));
         *      };
         *      g_array_free (ws_dbus_data->remote_method_data, TRUE);
-        * };*/
+        * };
+         */
 
        g_free (ws_dbus_data);
        g_debug ("| Freeing WSDBusData structure   |\n----------------------\n");
 };
 
 
+/** \param ws_dbus_data - pointer to a structure uniquely identifying the 
+ * application for D-BUS
+ * \param detailed_signal - string containing the signal name which will trigger 
+ * the function passed in the c_func parameter.
+ * \param c_func - is a pointer to the signal handling function.
+ * \param user_data - is the data passed directly to the signal handling
+ *  function
+ * \return \li WS_STATUS_OK - on success \li WS_STATUS_ERROR - on error
+ * \sa WSDBusConfig | ws_dbus_cb
+ */
 WSDBusStatus ws_dbus_set_cb (WSDBusData * ws_dbus_data,
                              gchar * method,
                              gpointer c_func,
@@ -461,6 +516,14 @@ WSDBusStatus ws_dbus_set_cb (WSDBusData * ws_dbus_data,
        return WS_DBUS_STATUS_OK;
 };
 
+/** \param ws_dbus_data - pointer to a structure uniquely identifying the 
+ * application for DBus
+ * \param method - method name\n
+ * \param arglist - a comma separated list of method's arguments (actually just
+ * their datatypes) finished with WS_DBUS_TYPE_INVALID
+ * \return \li WS_STATUS_OK - on success \li WS_STATUS_ERROR - on error
+ * \sa WSDBusDataType
+ */
 WSDBusStatus ws_dbus_add_method (WSDBusData * ws_dbus_data, gchar *method, ...)
 {
        WSDBusMethodData *method_data;
@@ -519,7 +582,12 @@ WSDBusStatus ws_dbus_add_method (WSDBusData * ws_dbus_data, gchar *method, ...)
        return WS_DBUS_STATUS_OK;
 };
 
-/* Converts an array of strings to an array of osso_rpc_t */
+/** Converts an array of strings to an array of osso_rpc_t which is necessary
+ * then sending data via DBUS
+ * \param data_bundle - a preallocated GArray of osso_rpc_t
+ * \param strings - a GArray of strings to be converted
+ * \return 
+ */
 WSDBusStatus ws_dbus_add_garray (GArray *data_bundle, GArray *strings)
 {
        osso_rpc_t *temp;
@@ -544,7 +612,16 @@ WSDBusStatus ws_dbus_add_garray (GArray *data_bundle, GArray *strings)
        };
 };
 
-/* Calls a specific method on remote object */
+/**Runs a remote method with specific name
+ *
+ * \param ws_dbus_data - pointer to a structure uniquely identifying the 
+ * application for DBus
+ * \param method - method name
+ * \param arglist - a comma separated list of pairs: datatype, value finished 
+ * with WS_DBUS_TYPE_INVALID
+ * \return \li WS_STATUS_OK - on success \li WS_STATUS_ERROR - on error
+ * \sa WSDBusDataType
+ */
 WSDBusStatus ws_dbus_call_method (WSDBusData * ws_dbus_data, gchar *method, ...)
 {
        va_list arglist;
@@ -649,6 +726,9 @@ WSDBusStatus ws_dbus_call_method (WSDBusData * ws_dbus_data, gchar *method, ...)
        return WS_DBUS_STATUS_OK;
 };
 
+/**This function will be used in future version of DBUS as soon as introspection
+ * is implemented
+ */
 WSDBusStatus ws_dbus_call_registered_method (WSDBusData * ws_dbus_data,
                                              gchar *method, ...)
 {