cpw.nader.asynclogging-3: 766a12c8: More doc cleanup

morshed.nader at gmail.com morshed.nader at gmail.com
Mon Mar 21 00:13:04 EDT 2011


----------------------------------------------------------------------
Revision: 766a12c88da00b95022b367bad070255f3c17f9d
Parent:   04fd65c5e3381c1f0aa261f0c3b9fef497938c66
Author:   morshed.nader at gmail.com
Date:     03/21/11 00:02:15
Branch:   im.pidgin.cpw.nader.asynclogging-3
URL: http://d.pidgin.im/viewmtn/revision/info/766a12c88da00b95022b367bad070255f3c17f9d

Changelog: 

More doc cleanup

Changes against parent 04fd65c5e3381c1f0aa261f0c3b9fef497938c66

  patched  libpurple/commonlog.c
  patched  libpurple/commonlog.h
  patched  libpurple/log.h

-------------- next part --------------
============================================================
--- libpurple/log.h	e841f8659f43001b5e3cb1f0cdccb07b0c312f5f
+++ libpurple/log.h	c5c1f1de7d69490450b52aee0b91c1a35cea4fcb
@@ -498,6 +498,8 @@ gchar *purple_log_read_finish(PurpleLog 
  * Returns the size of a log
  *
  * @param log          The log
+ * @param cancellable  (allow-none): GCancellable object
+ * @param error        (out) (allow-none): a GError location to store the error
  *
  * @return             The size of the log, in bytes
  */
@@ -536,10 +538,12 @@ gssize purple_log_get_size_finish(Purple
 /**
  * Returns a list of all available logs for a given logger
  *
- * @param log          A dummy log of the type of logger to list the logs of
+ * @param log          A dummy log of the type of logger to use
  * @param type         The type of the log
  * @param name         The name of the log
  * @param account      The account
+ * @param cancellable  (allow-none): GCancellable object
+ * @param error        (out) (allow-none): a GError location to store the error
  *
  * @return             A sorted list of logs
  */
@@ -550,7 +554,7 @@ GList *purple_log_get_logs(PurpleLog *lo
 /**
  * Asynchronously gets a list of all available logs for a given logger
  *
- * @param log          A dummy log of the type of logger to list the logs of
+ * @param log          A dummy log of the type of logger to use
  * @param type         The type of the log
  * @param name         The name of the log
  * @param account      The account
@@ -573,6 +577,7 @@ void purple_log_get_logs_async(PurpleLog
  * Note: Make sure to examine that error is not NULL as it is completely possible
  * for the list to be empty and the function to return NULL without an error
  *
+ * @param log          A dummy log of the type of logger to use
  * @param res          A GAsyncResult
  * @param error        (out) (allow-none): a GError location to store the error
  *
@@ -637,7 +642,7 @@ GList *purple_logs_get_logs_finish(GAsyn
 /**
  * Returns a list of all available system logs
  *
- * @param log          A dummy log of the type of logger to list the logs of
+ * @param log          A dummy log of the type of logger to use
  * @param account      The account
  * @param cancellable  (allow-none): GCancellable object
  * @param error        (out) (allow-none): a GError location to store the error
@@ -650,7 +655,7 @@ GList *purple_log_get_system_logs(Purple
 /**
  * Asychronously gets a list of all available system logs
  *
- * @param log          A dummy log of the type of logger to list the logs of
+ * @param log          A dummy log of the type of logger to use
  * @param account      The account
  * @param io_priority  The io priority of the request
  * @param cancellable  (allow-none): GCancellable object
@@ -670,6 +675,7 @@ void purple_log_get_system_logs_async(Pu
  * Note: Make sure to examine that error is not NULL as it is completely possible
  * for the list to be empty and the function to return NULL without an error
  *
+ * @param log          A dummy log of the type of logger to use
  * @param res          A GAsyncResult
  * @param error        (out) (allow-none): a GError location to store the error
  *
@@ -728,11 +734,14 @@ GList *purple_logs_get_system_logs_finis
 GList *purple_logs_get_system_logs_finish(GAsyncResult *res, GError **error);
 
 /**
- * Returns the size, in bytes, of all available logs in this conversation
+ * Returns the size, in bytes, of all logs of a conversation
  *
+ * @param log          A dummy log of the type of logger to use
  * @param type         The type of the log
  * @param name         The name of the log
  * @param account      The account
+ * @param cancellable  (allow-none): GCancellable object
+ * @param error        (out) (allow-none): a GError location to store the error
  *
  * @return             Size of logs or -1 on error
  */
@@ -741,8 +750,10 @@ gssize purple_log_get_total_size(PurpleL
 	GError **error);
 
 /**
- * Asychronously gets the size, in bytes, of all available logs in this conversation
+ * Asychronously gets the size, in bytes, of all logs of a conversation
+ * See purple_log_get_total_size() for more details.
  *
+ * @param log          A dummy log of the type of logger to use
  * @param type         The type of the log
  * @param name         The name of the log
  * @param account      The account
@@ -834,15 +845,20 @@ gssize purple_logs_get_total_size_finish
  * destroyed. If a log set is removed from the table, it
  * must be freed with purple_log_set_free().
  *
+ * @param log          A dummy log of the type of logger to use
+ * @param cancellable  (allow-none): GCancellable object
+ * @param error        (out) (allow-none): a GError location to store the error
+ *
  * @return             A table of all available unique log sets
  */
-GHashTable *purple_log_get_log_sets(PurpleLog *, GCancellable *cancellable,
+GHashTable *purple_log_get_log_sets(PurpleLog *log, GCancellable *cancellable,
 	GError **error);
 
 /**
  * Asychronously gets a hash table of log sets.
  * For more details, see purple_log_get_log_sets().
  *
+ * @param log          A dummy log of the type of logger to use
  * @param io_priority  The io priority of the request
  * @param cancellable  (allow-none): GCancellable object
  * @param cb           (allow-none): A GAsyncReadyCallback to call when the
@@ -857,6 +873,7 @@ void purple_log_get_log_sets_async(Purpl
 /**
  * Finishes asynchronously getting a hash table of log sets
  *
+ * @param log          A dummy log of the type of logger to use
  * @param res          A GAsyncResult
  * @param error        (out) (allow-none): a GError location to store the error
  *
@@ -913,16 +930,19 @@ GHashTable *purple_logs_get_log_sets_fin
  * Returns the activity score of a log, based on total size in bytes,
  * which is then decayed based on age
  *
- * @param type         The type of the log
+ * @param chat_type    The type of the log
  * @param name         The name of the log
  * @param account      The account
+ * @param cancellable  (allow-none): GCancellable object
+ * @param error        (out) (allow-none): a GError location to store the error
  *
  * @return             The activity score
  *
  * @since 2.6.0
  */
-gssize purple_log_get_activity_score(PurpleLogChatType type, const gchar *name,
-	PurpleAccount *account, GCancellable *cancellable, GError **error);
+gssize purple_log_get_activity_score(PurpleLogChatType chat_type,
+	const gchar *name, PurpleAccount *account, GCancellable *cancellable,
+	GError **error);
 
 /**
  * Asychronously gets the activity score of a log
============================================================
--- libpurple/commonlog.c	450065a608ea4ea6b6cfa2dbf396b0adae4f4a72
+++ libpurple/commonlog.c	63a51139fe74ce375ed7ea8880f4357b6a71dbd1
@@ -397,8 +397,9 @@ GList *
 }
 
 GList *
-purple_log_common_lister(PurpleLogChatType chat_type, const gchar *name, PurpleAccount *account,
-	const gchar *ext, GType log_type, GCancellable *cancellable, GError **error)
+purple_log_common_lister(PurpleLogChatType chat_type, const gchar *name,
+	PurpleAccount *account, const gchar *ext, GType log_type,
+	GCancellable *cancellable, GError **error)
 {
 	GDir *dir;
 	GList *list = NULL;
============================================================
--- libpurple/commonlog.h	cc0d3ed6d00ffe8d0e99e140aa7ab0c664135933
+++ libpurple/commonlog.h	14458e75e6526e580d1b6a726b3456b1b2a54a61
@@ -100,8 +100,11 @@ gssize purple_common_log_get_length(Purp
  *
  * @param log          The log to write to
  * @param ext          (allow-none): The file extension to give to this log file
+ * @param cancellable  (allow-none): GCancellable object
+ * @param error        (out) (allow-none): a GError location to store the error
  */
-gboolean purple_log_common_writer(PurpleLog *log, const gchar *ext, GCancellable *cancellable, GError **error);
+gboolean purple_log_common_writer(PurpleLog *log, const gchar *ext,
+	GCancellable *cancellable, GError **error);
 
 /**
  * Asynchronously opens a new log in the standard log location
@@ -116,13 +119,14 @@ gboolean purple_log_common_writer(Purple
  * @param cb           (allow-none): A GAsyncReadyCallback to call when the request is satisfied
  * @param userdata     (allow-none): The data to pass to callback function
  */
-void purple_log_common_writer_async(PurpleLog *log, const gchar *ext, gint io_priority, GCancellable *cancellable, GAsyncReadyCallback cb, gpointer userdata);
+void purple_log_common_writer_async(PurpleLog *log, const gchar *ext,
+	gint io_priority, GCancellable *cancellable, GAsyncReadyCallback cb,
+	gpointer userdata);
 
 /**
  * Asynchronously opens a new log in the standard log location
  *
- * For more details, see purple_log_common_writer() which is
- * the synchronous version of this call.
+ * See purple_log_common_writer() for more details.
  *
  * @param log          The log to write to
  * @param res          A GAsyncResult
@@ -130,7 +134,8 @@ void purple_log_common_writer_async(Purp
  *
  * @return             %TRUE if the log was created, %FALSE otherwise
  */
-gboolean purple_log_common_writer_finish(PurpleLog *log, GAsyncResult *res, GError **error);
+gboolean purple_log_common_writer_finish(PurpleLog *log, GAsyncResult *res,
+	GError **error);
 
 /**
  * Returns a sorted list of logs of the requested type
@@ -141,15 +146,20 @@ gboolean purple_log_common_writer_finish
  * It should only be passed to purple_log_logger_new() and never
  * called directly.
  *
- * @param type         The type of the logs being listed
+ * @param chat_type    The type of the logs being listed
  * @param name         The name of the log
  * @param account      The account of the log
  * @param ext          The file extension this log format uses
- * @param log_type     The log type to create the new logs with, or G_TYPE_INVALID to use the default type
+ * @param log_type     The log type to create the new logs with, or
+ *                     G_TYPE_INVALID to use the default type
+ * @param cancellable  (allow-none): GCancellable object
+ * @param error        (out) (allow-none): a GError location to store the error
  *
  * @return             The sorted list of logs matching the parameters
  */
-GList *purple_log_common_lister(PurpleLogChatType type, const gchar *name, PurpleAccount *account, const gchar *ext, GType log_type, GCancellable *cancellable, GError **error);
+GList *purple_log_common_lister(PurpleLogChatType chat_type, const gchar *name,
+	PurpleAccount *account, const gchar *ext, GType log_type,
+	GCancellable *cancellable, GError **error);
 
 /**
  * Asynchronously gets a sorted list of log of the requested type.
@@ -159,15 +169,19 @@ GList *purple_log_common_lister(PurpleLo
  * @param name         The name of the log
  * @param account      The account of the log
  * @param ext          The file extension this log format uses
- * @param log_type     The log type to create the new logs with, or G_TYPE_INVALID to use the default type
+ * @param log_type     The log type to create the new logs with, or 
+ *                     G_TYPE_INVALID to use the default type
  * @param io_priority  The io priority of the request
  * @param cancellable  (allow-none): GCancellable object
- * @param cb           (allow-none): A GAsyncReadyCallback to call when the request is satisfied
+ * @param cb           (allow-none): A GAsyncReadyCallback to call when the 
+ *                     request is satisfied
  * @param userdata     (allow-none): The data to pass to callback function
  *
- * @since 2.8.0
+ * @since 3.0.0
  */
-void purple_log_common_lister_async(PurpleLogChatType type, const gchar *name, PurpleAccount *account, const gchar *ext, GType log_type, gint io_priority, GCancellable *cancellable, GAsyncReadyCallback cb, gpointer userdata);
+void purple_log_common_lister_async(PurpleLogChatType type, const gchar *name,
+	PurpleAccount *account, const gchar *ext, GType log_type, gint io_priority,
+	GCancellable *cancellable, GAsyncReadyCallback cb, gpointer userdata);
 
 /**
  * Finishes asynchronously listing the logs of a requested type.
@@ -181,7 +195,7 @@ void purple_log_common_lister_async(Purp
  *
  * @return             A sorted list of list or %NULL on error
  *
- * @since 2.8.0
+ * @since 3.0.0
  */
 GList *purple_log_common_lister_finish(GAsyncResult *res, GError **error);
 
@@ -221,10 +235,11 @@ gssize purple_log_common_total_sizer(Pur
  * @param ext          The file extension this log format uses
  * @param io_priority  The io priority of the request
  * @param cancellable  (allow-none): GCancellable object
- * @param cb           (allow-none): A GAsyncReadyCallback to call when the request is satisfied
+ * @param cb           (allow-none): A GAsyncReadyCallback to call when the
+ *                     request is satisfied
  * @param userdata     (allow-none): The data to pass to callback function
  *
- * @since 2.8.0
+ * @since 3.0.0
  */
 void purple_log_common_total_sizer_async(PurpleLogChatType chat_type,
 	const gchar *name, PurpleAccount *account, const gchar *ext,
@@ -239,7 +254,7 @@ void purple_log_common_total_sizer_async
  *
  * @return             size of file or -1 on error
  *
- * @since 2.8.0
+ * @since 3.0.0
  */
 gssize purple_log_common_total_sizer_finish(GAsyncResult *res, GError **error);
 


More information about the Commits mailing list