Improving comments ang gtk-doc strings

3 files changed, 44 insertions, 13 deletions

diff --git a/telepathy-logger/channel-text.c b/telepathy-logger/channel-text.c
index 3fc7d3ba3..c73131078 100644
--- a/telepathy-logger/channel-text.c
+++ b/telepathy-logger/channel-text.c
@@ -709,12 +709,11 @@ got_message_pending_messages_cb (TpProxy *proxy,
         {
           PATH_DEBUG (proxy, "pending msg %s already logged, not logging",
               tpl_message_token);
-          /* I remove the element so that at the end of the cycle I'll have
-           * only elements that I could not find in the pending msg list,
-           * which are stale elements */
-          indexed_pending_msg = g_list_remove_link (indexed_pending_msg, l);
+          /* Removing the element is a way to mark it as "present in pending
+           * message list", being also able to identify all the messages not
+           * present in the list, which I'll consider as stale entries */
           g_free (l->data);
-          g_list_free (l);
+          indexed_pending_msg = g_list_delete_link (indexed_pending_msg, l);
 
           /* do not log messages which log_id is present in LogStoreIndex */
           continue;
diff --git a/telepathy-logger/log-entry.c b/telepathy-logger/log-entry.c
index bffcaa1f7..e8717945a 100644
--- a/telepathy-logger/log-entry.c
+++ b/telepathy-logger/log-entry.c
@@ -259,14 +259,22 @@ tpl_log_entry_class_init (TplLogEntryClass *klass)
    * TplLogEntry::pending-msg-id:
    *
    * The pending message id for the current log entry.
-   * The construction-time value if #TPL_LOG_ENTRY_MSG_ID_ACKNOWLEDGED,
-   * meaning that the log entry is considered already acknoledged.
-   * An object instantiating a TplLogEntry subclass should explicitly set ths
+   * The default value, is #TPL_LOG_ENTRY_MSG_ID_UNKNOWN,
+   * meaning that it's not possible to know if the message is pending or has
+   * been acknowledged.
+   *
+   * An object instantiating a TplLogEntry subclass should explicitly set it
+   * to a valid msg-id number (id>=0) or to #TPL_LOG_ENTRY_MSG_ID_ACKNOWLEDGED
+   * when acknowledged or if the entry is a result of
+   * 'sent' signal.
+   * In fact a sent entry is considered as 'automatically' ACK by TPL.
    *
    * The pending message id value is only meaningful when associated to the
    * #TplLogEntry::channel-path property.
-   * The couple (channel-path, pending-msg-id) cannot be considered unique.
-   * Use #TplLogEntry::log-id for a TPL-unique identifier.
+   * The couple (channel-path, pending-msg-id) cannot be considered unique,
+   * though, since a message-id might be reused over time.
+   *
+   * Use #TplLogEntry::log-id for a unique identifier within TPL.
    */
   param_spec = g_param_spec_int ("pending-msg-id",
       "PendingMessageId",
@@ -277,6 +285,16 @@ tpl_log_entry_class_init (TplLogEntryClass *klass)
   g_object_class_install_property (object_class, PROP_PENDING_MSG_ID,
       param_spec);
 
+  /**
+   * TplLogEntry::log-id:
+   *
+   * A token which can be trusted as unique over time within TPL.
+   *
+   * Always use this token if you need to identify a TplLogEntry uniquely.
+   *
+   * @see_also: #Util:create_message_token for more information about how it's
+   * built.
+   */
   param_spec = g_param_spec_string ("log-id",
       "LogId",
       "Log identification token, it's unique among existing LogEntry, if two "
@@ -502,8 +520,9 @@ tpl_log_entry_set_signal_type (TplLogEntry *self,
  * @self: TplLogentry instance
  * @data: the pending message ID
  *
- * Sets the value of the pending message id, or
- * #TPL_LOG_ENTRY_MSG_ID_ACKNOWLEDGED to set @self as aknowledged.
+ * Sets @self to be associated to pending message id @data.
+ *
+ * @see_also: #TplLogEntry::pending-msg-id for special values.
  */
 void
 tpl_log_entry_set_pending_msg_id (TplLogEntry *self,
diff --git a/telepathy-logger/log-entry.h b/telepathy-logger/log-entry.h
index bd541147b..b0cb1e55c 100644
--- a/telepathy-logger/log-entry.h
+++ b/telepathy-logger/log-entry.h
@@ -34,7 +34,20 @@ G_BEGIN_DECLS
 #define TPL_IS_LOG_ENTRY_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), TPL_TYPE_LOG_ENTRY))
 #define TPL_LOG_ENTRY_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), TPL_TYPE_LOG_ENTRY, TplLogEntryClass))
 
-/* value used to identify a ack'd message with the 'pending-msg-id' prop */
+/**
+ * TPL_LOG_ENTRY_MSG_ID_UNKNOWN:
+ *
+ * special value used to declare a message with a unknown status (ie pre
+ * #tpl_log_entry_set_pending_msg_id call or when an error obtaining the
+ * actual value  occurs)
+ */
+#define TPL_LOG_ENTRY_MSG_ID_UNKNOWN -2
+
+/**
+ * TPL_LOG_ENTRY_MSG_ID_ACKNOWLEDGED:
+ *
+ * special value used to identify a ack'd messages
+ */
 #define TPL_LOG_ENTRY_MSG_ID_ACKNOWLEDGED -1
 
 typedef enum