TP Style fixes and gtk-doc src documentation improved

3 files changed, 168 insertions, 20 deletions

diff --git a/telepathy-logger/log-manager.c b/telepathy-logger/log-manager.c
index 10cb6bfad..21c7e6815 100644
--- a/telepathy-logger/log-manager.c
+++ b/telepathy-logger/log-manager.c
@@ -94,7 +94,7 @@ log_manager_finalize (GObject *object)
 
   g_list_foreach (priv->stores, (GFunc) g_object_unref, NULL);
   g_list_free (priv->stores);
-  /* no unref needed here, the only reference kept is in priv->stores */
+  /* no unref needed here, the only references kept is in priv->stores */
   g_list_free (priv->writable_stores);
   g_list_free (priv->readable_stores);
 
@@ -210,6 +210,9 @@ tpl_log_manager_dup_singleton (void)
  * Every TplLogManager is guaranteed to have at least TplLogStore a readable
  * and a writable LogStore regitered.
  *
+ * It applies for any registered TplLogStore with #TplLogstore:writable property
+ * %TRUE
+ *
  * Returns: %TRUE if the message has been successfully added, %FALSE otherwise.
  */
 gboolean
@@ -310,7 +313,22 @@ tpl_log_manager_register_log_store (TplLogManager *self,
   return TRUE;
 }
 
+/**
+ * tpl_log_manager_exists:
+ * @manager: TplLogManager
+ * @account: TpAccount
+ * @chat_id: a non-NULL chat id
+ * @chatroom: whether @chat_id is a chatroom or not
+ *
+ * Checks if @chat_id does exist for @account and
+ * - is a chatroom, if @chatroom is %TRUE
+ * - is not a chatroom, if @chatroom is %FALSE
+ *
+ * It applies for any registered TplLogStore with the #TplLogStore:readable
+ * property %TRUE.
 
+ * Returns: %TRUE if @chat_id exists, %FALSE otherwise
+ */
 gboolean
 tpl_log_manager_exists (TplLogManager *manager,
     TpAccount *account,
@@ -335,8 +353,25 @@ tpl_log_manager_exists (TplLogManager *manager,
   return FALSE;
 }
 
-/*
- * @returns a list of gchar dates
+
+/**
+ * tpl_log_manager_get_dates:
+ * @manager: a TplLogManager
+ * @account: a TpAccount
+ * @chat_id: a non-NULL chat identifier
+ * @chatroom: whather if the request is related to a chatroom or not.
+ *
+ * Retrieves a list of dates, in string form YYYYMMDD, corrisponding to each day
+ * at least a message was sent to or received from @chat_id.
+ * @chat_id may be the id of a buddy or a chatroom, depending on the value of
+ * @chatroom.
+ *
+ * It applies for any registered TplLogStore with the #TplLogStore:readable
+ * property %TRUE.
+ *
+ * Returns: a GList of (char *), to be freed using something like
+ * g_list_foreach (lst, g_free, NULL);
+ * g_list_free (lst);
  */
 GList *
 tpl_log_manager_get_dates (TplLogManager *manager,
@@ -352,7 +387,7 @@ tpl_log_manager_get_dates (TplLogManager *manager,
 
   priv = GET_PRIV (manager);
 
-  for (l = priv->stores; l != NULL; l = g_list_next (l))
+  for (l = priv->readable_stores; l != NULL; l = g_list_next (l))
     {
       TplLogStore *store = TPL_LOG_STORE (l->data);
       GList *new;
@@ -375,6 +410,7 @@ tpl_log_manager_get_dates (TplLogManager *manager,
   return out;
 }
 
+
 GList *
 tpl_log_manager_get_messages_for_date (TplLogManager *manager,
     TpAccount *account,
@@ -390,7 +426,7 @@ tpl_log_manager_get_messages_for_date (TplLogManager *manager,
 
   priv = GET_PRIV (manager);
 
-  for (l = priv->stores; l != NULL; l = g_list_next (l))
+  for (l = priv->readable_stores; l != NULL; l = g_list_next (l))
     {
       TplLogStore *store = TPL_LOG_STORE (l->data);
 
@@ -445,14 +481,14 @@ tpl_log_manager_get_filtered_messages (TplLogManager *manager,
 
   /* Get num_messages from each log store and keep only the
    * newest ones in the out list. Keep that list sorted: Older first. */
-  for (l = priv->stores; l != NULL; l = g_list_next (l))
+  for (l = priv->readable_stores; l != NULL; l = g_list_next (l))
     {
       TplLogStore *store = TPL_LOG_STORE (l->data);
       GList *new;
 
       new = tpl_log_store_get_filtered_messages (store, account, chat_id,
           chatroom, num_messages, filter, user_data);
-      while (new)
+      while (new != NULL)
         {
           if (i < num_messages)
             {
@@ -485,6 +521,21 @@ tpl_log_manager_get_filtered_messages (TplLogManager *manager,
 }
 
 
+/**
+ * tpl_log_manager_search_hit_compare:
+ * @a: a TplLogSerachHit
+ * @b: a TplLogSerachHit
+ *
+ * Compare @a and @b, returning an ordered relation between the two.
+ * Acts similar to the strcmp family, with the difference that since
+ * TplLogSerachHit is not a plain string, but a struct, the order relation
+ * will be a coposition of:
+ * - the order relation between @a.chat_it and @b.chat_id
+ * - the order relation between @a.chatroom and @b.chatroom, being
+ *   chatroom = %FALSE > chatroom = %TRUE (meaning: a 1-1 message is greater
+ *   than a chatroom one).
+ *
+ * Returns: -1 if a > b, 1 if a < b or 0 is a == b */
 gint
 tpl_log_manager_search_hit_compare (TplLogSearchHit *a,
     TplLogSearchHit *b)
@@ -673,7 +724,7 @@ static void
 tpl_log_manager_chat_info_free (TplLogManagerChatInfo *data)
 {
   if (data->account != NULL)
-     g_object_unref (data->account);
+    g_object_unref (data->account);
   if (data->chat_id != NULL)
     g_free (data->chat_id);
   if (data->date != NULL)
@@ -726,6 +777,7 @@ _tpl_log_manager_call_async_operation (TplLogManager *manager,
 }
 /* end of Async common function */
 
+
 /* Start of add_message async implementation */
 static void
 _add_message_async_thread (GSimpleAsyncResult *simple,
@@ -774,7 +826,7 @@ tpl_log_manager_add_message_async (TplLogManager *manager,
   async_data->manager = g_object_ref (manager);
   async_data->request = chat_info;
   async_data->request_free =
-      (TplLogManagerFreeFunc) tpl_log_manager_chat_info_free;
+    (TplLogManagerFreeFunc) tpl_log_manager_chat_info_free;
   async_data->cb = callback;
   async_data->user_data = user_data;
 
@@ -849,7 +901,7 @@ tpl_log_manager_get_dates_async (TplLogManager *manager,
   async_data->manager = g_object_ref (manager);
   async_data->request = chat_info;
   async_data->request_free =
-      (TplLogManagerFreeFunc) tpl_log_manager_chat_info_free;
+    (TplLogManagerFreeFunc) tpl_log_manager_chat_info_free;
   async_data->cb = callback;
   async_data->user_data = user_data;
 
@@ -1020,7 +1072,7 @@ tpl_log_manager_get_filtered_messages_async (TplLogManager *manager,
   async_data->manager = g_object_ref (manager);
   async_data->request = chat_info;
   async_data->request_free =
-      (TplLogManagerFreeFunc) tpl_log_manager_chat_info_free;
+    (TplLogManagerFreeFunc) tpl_log_manager_chat_info_free;
   async_data->cb = callback;
   async_data->user_data = user_data;
 
diff --git a/telepathy-logger/log-store-empathy.c b/telepathy-logger/log-store-empathy.c
index 16635b3c2..62b09467f 100644
--- a/telepathy-logger/log-store-empathy.c
+++ b/telepathy-logger/log-store-empathy.c
@@ -740,7 +740,7 @@ log_store_empathy_search_hit_new (TplLogStore *self,
   return hit;
 }
 
-
+/* returns a Glist of TplLogEntryText instances */
 static GList *
 log_store_empathy_get_messages_for_file (TplLogStore *self,
     TpAccount *account,
@@ -817,7 +817,7 @@ log_store_empathy_get_messages_for_file (TplLogStore *self,
       cm_id_str = (gchar *) xmlGetProp (node, (const xmlChar *) "cm_id");
 
       if (is_user_str)
-        is_user = strcmp (is_user_str, "true") == 0;
+        is_user = (!tp_strdiff (is_user_str, "true"));
 
       if (msg_type_str)
         msg_type = tpl_log_entry_text_message_type_from_str (msg_type_str);
@@ -1061,6 +1061,7 @@ log_store_empathy_get_chats_for_dir (TplLogStore *self,
 }
 
 
+/* returns a Glist of TplLogEntryText instances */
 static GList *
 log_store_empathy_get_messages_for_date (TplLogStore *self,
     TpAccount *account,
@@ -1084,6 +1085,7 @@ log_store_empathy_get_messages_for_date (TplLogStore *self,
   return messages;
 }
 
+
 static GList *
 log_store_empathy_get_chats (TplLogStore *self,
     TpAccount *account)
@@ -1119,6 +1121,7 @@ log_store_empathy_get_name (TplLogStore *self)
   return priv->name;
 }
 
+
 /* returns am absolute path for the base directory of LogStore */
 static const gchar *
 log_store_empathy_get_basedir (TplLogStore *self)
@@ -1234,7 +1237,7 @@ log_store_empathy_get_filtered_messages (TplLogStore *self,
 
   dates = log_store_empathy_get_dates (self, account, chat_id, chatroom);
 
-  for (l = g_list_last (dates); l && i < num_messages;
+  for (l = g_list_last (dates); l != NULL && i < num_messages;
        l = g_list_previous (l))
     {
       GList *new_messages, *n, *next;
diff --git a/telepathy-logger/log-store.c b/telepathy-logger/log-store.c
index afe1d55f2..31e1aecfa 100644
--- a/telepathy-logger/log-store.c
+++ b/telepathy-logger/log-store.c
@@ -108,6 +108,16 @@ tpl_log_store_exists (TplLogStore *self,
 }
 
 
+/**
+ * tpl_log_store_add_message:
+ * @self: a TplLogStore
+ * @message: an instance of a subclass of TplLogEntry (ie TplLogEntryText)
+ * @error: memory location used if an error occurs
+ *
+ * Sends @message to the LogStore @self, in order to be stored.
+ *
+ * Returns: %TRUE if succeeds, %FALSE with @error set otherwise
+ */
 gboolean
 tpl_log_store_add_message (TplLogStore *self,
     TplLogEntry *message,
@@ -124,6 +134,22 @@ tpl_log_store_add_message (TplLogStore *self,
 }
 
 
+/**
+ * tpl_log_store_get_dates:
+ * @self: a TplLogStore
+ * @account: a TpAccount
+ * @chat_id: a non-NULL chat identifier
+ * @chatroom: whather if the request is related to a chatroom or not.
+ *
+ * Retrieves a list of dates, in string form YYYYMMDD, corrisponding to each day
+ * at least a message was sent to or received from @chat_id.
+ * @chat_id may be the id of a buddy or a chatroom, depending on the value of
+ * @chatroom.
+ *
+ * Returns: a GList of (char *), to be freed using something like
+ * g_list_foreach (lst, g_free, NULL);
+ * g_list_free (lst);
+ */
 GList *
 tpl_log_store_get_dates (TplLogStore *self,
     TpAccount *account,
@@ -138,6 +164,20 @@ tpl_log_store_get_dates (TplLogStore *self,
 }
 
 
+/**
+ * tpl_log_store_get_messages_for_date:
+ * @self: a TplLogStore
+ * @account: a TpAccount
+ * @chat_id: a non-NULL chat identifier
+ * @chatroom: whather if the request is related to a chatroom or not.
+ * @date: a date, in YYYYMMDD string form
+ *
+ * Retrieves a list of text messages, with timestamp matching @date.
+ *
+ * Returns: a GList of TplLogEntryText, to be freed using something like
+ * g_list_foreach (lst, g_object_unref, NULL);
+ * g_list_free (lst);
+ */
 GList *
 tpl_log_store_get_messages_for_date (TplLogStore *self,
     TpAccount *account,
@@ -167,6 +207,18 @@ tpl_log_store_get_recent_messages (TplLogStore *self,
 }
 
 
+/**
+ * tpl_log_store_get_chats:
+ * @self: a TplLogStore
+ * @account: a TpAccount
+ *
+ * Retrieves a list of search hits, corrisponding to each buddy/chatroom id
+ * the user exchanged at least a message with, using @account.
+ *
+ * Returns: a GList of (TplLogSearchHit *), to be freed using something like
+ * g_list_foreach (lst, tpl_log_manager_search_free, NULL);
+ * g_list_free (lst);
+ */
 GList *
 tpl_log_store_get_chats (TplLogStore *self,
     TpAccount *account)
@@ -178,21 +230,45 @@ tpl_log_store_get_chats (TplLogStore *self,
 }
 
 
-
+/**
+ * tpl_log_store_search_in_identifier_chats_new:
+ * @self: a TplLogStore
+ * @account: a TpAccount
+ * @chat_id: a chat_id
+ * @text: a text to be searched among @chat_id messages
+ *
+ * Searches textual log entries related to @chat_id and matching @text
+ *
+ * Returns: a GList of (TplLogSearchHit *), to be freed using something like
+ * g_list_foreach (lst, tpl_log_manager_search_free, NULL);
+ * g_list_free (lst);
+ */
 GList *
 tpl_log_store_search_in_identifier_chats_new (TplLogStore *self,
     TpAccount *account,
-    gchar const *identifier,
+    gchar const *chat_id,
     const gchar *text)
 {
-  if (!TPL_LOG_STORE_GET_INTERFACE (self)->search_new)
+  if (!TPL_LOG_STORE_GET_INTERFACE (self)->search_in_identifier_chats_new)
     return NULL;
 
   return TPL_LOG_STORE_GET_INTERFACE (self)->search_in_identifier_chats_new (self,
-      account, identifier, text);
+      account, chat_id, text);
 }
 
 
+/**
+ * tpl_log_store_search_new:
+ * @self: a TplLogStore
+ * @text: a text to be searched among @chat_id messages
+ *
+ * Searches all textual log entries (all accounts and all chat_ids)  matching
+ * @text
+ *
+ * Returns: a GList of (TplLogSearchHit *), to be freed using something like
+ * g_list_foreach (lst, tpl_log_manager_search_free, NULL);
+ * g_list_free (lst);
+ */
 GList *
 tpl_log_store_search_new (TplLogStore *self,
     const gchar *text)
@@ -204,6 +280,25 @@ tpl_log_store_search_new (TplLogStore *self,
 }
 
 
+/**
+ * tpl_log_store_search_in_identifier_chats_new:
+ * @self: a TplLogStore
+ * @account: a TpAccount
+ * @chat_id: a chat_id
+ * @chatroom: whether the @chat_id is related to a chatroom or not
+ * @num_messages: max number of messages to return
+ * @filter: filter function
+ * @user_data: data be passed to @filter, may be NULL
+ *
+ * Filters all messages related to @chat_id, using the boolean function
+ * @filter.
+ * It will return at most the last (ie most recent) @num_messages messages.
+ * Pass G_MAXUINT if all the message are needed.
+ *
+ * Returns: a GList of TplLogEntryText, to be freed using something like
+ * g_list_foreach (lst, g_object_unref, NULL);
+ * g_list_free (lst);
+ */
 GList *
 tpl_log_store_get_filtered_messages (TplLogStore *self,
     TpAccount *account,
@@ -239,5 +334,3 @@ tpl_log_store_is_readable (TplLogStore *self)
 
   return TPL_LOG_STORE_GET_INTERFACE (self)->is_readable (self);
 }
-
-