/soc/2013/ankitkv/gobjectification: 901dfa763f15: Fix some gtk-d...
Ankit Vani
a at nevitus.org
Wed Feb 5 11:13:46 EST 2014
Changeset: 901dfa763f15c700a4506ec268ce3d30a56a88d0
Author: Ankit Vani <a at nevitus.org>
Date: 2014-02-05 21:38 +0530
Branch: gtkdoc-conversion
URL: https://hg.pidgin.im/soc/2013/ankitkv/gobjectification/rev/901dfa763f15
Description:
Fix some gtk-doc warnings till proxy.c
diffstat:
libpurple/eventloop.h | 138 +++++++++++++++++----------------------
libpurple/http.c | 8 +-
libpurple/http.h | 10 +-
libpurple/idle.c | 2 +-
libpurple/imgstore.h | 5 +-
libpurple/internal.h | 6 +-
libpurple/keyring.c | 2 +-
libpurple/keyring.h | 4 +-
libpurple/log.h | 5 +-
libpurple/media-gst.h | 2 +-
libpurple/media/backend-fs2.h | 6 +-
libpurple/media/backend-iface.h | 2 +-
libpurple/mime.c | 4 +-
libpurple/network.c | 8 +-
libpurple/notify.c | 8 +-
libpurple/notify.h | 2 +-
libpurple/ntlm.c | 2 +-
libpurple/plugin.c | 2 +-
libpurple/plugin.h | 43 ++++++------
libpurple/pounce.c | 18 ++--
libpurple/presence.h | 12 +--
libpurple/proxy.c | 48 +++++++------
22 files changed, 161 insertions(+), 176 deletions(-)
diffs (truncated from 754 to 300 lines):
diff --git a/libpurple/eventloop.h b/libpurple/eventloop.h
--- a/libpurple/eventloop.h
+++ b/libpurple/eventloop.h
@@ -58,101 +58,85 @@ typedef struct _PurpleEventLoopUiOps Pur
/**
* PurpleEventLoopUiOps:
+ * @timeout_add: Should create a callback timer with an interval measured in
+ * milliseconds. The supplied @function should be called every
+ * @interval seconds until it returns %FALSE, after which it
+ * should not be called again.
+ * <sbr/>Analogous to g_timeout_add in glib.
+ * <sbr/>Note: On Win32, this function may be called from a thread
+ * other than the libpurple thread. You should make sure to detect
+ * this situation and to only call "function" from the libpurple
+ * thread.
+ * <sbr/>See purple_timeout_add().
+ * <sbr/>@interval: the interval in
+ * <emphasis>milliseconds</emphasis> between
+ * calls to @function.
+ * <sbr/>@data: arbitrary data to be passed to @function at each
+ * call.
+ * <sbr/>Returns: a handle for the timeout, which can be passed to
+ * @timeout_remove.
+ * @timeout_remove: Should remove a callback timer. Analogous to
+ * g_source_remove() in glib.
+ * <sbr/>See purple_timeout_remove().
+ * <sbr/>@handle: an identifier for a timeout, as returned by
+ * @timeout_add.
+ * <sbr/>Returns: %TRUE if the timeout identified by @handle
+ * was found and removed.
+ * @input_add: Should add an input handler. Analogous to g_io_add_watch_full()
+ * in glib.
+ * <sbr/>See purple_input_add().
+ * <sbr/>@fd: a file descriptor to watch for events
+ * <sbr/>@cond: a bitwise OR of events on @fd for which @func
+ * should be called.
+ * <sbr/>@func: a callback to fire whenever a relevant event on
+ * @fd occurs.
+ * <sbr/>@user_data: arbitrary data to pass to @fd.
+ * <sbr/>Returns: an identifier for this input handler, which can
+ * be passed to @input_remove.
+ * @input_remove: Should remove an input handler. Analogous to g_source_remove()
+ * in glib.
+ * <sbr/>See purple_input_remove().
+ * <sbr/>@handle: an identifier, as returned by #input_add.
+ * <sbr/>Returns: %TRUE if the input handler was found and
+ * removed.
+ * @input_get_error: If implemented, should get the current error status for an
+ * input.
+ * <sbr/>Implementation of this UI op is optional. Implement
+ * it if the UI's sockets or event loop needs to customize
+ * determination of socket error status. If unimplemented,
+ * <literal>getsockopt(2)</literal> will be used instead.
+ * <sbr/>See purple_input_get_error().
+ * @timeout_add_seconds: If implemented, should create a callback timer with an
+ * interval measured in seconds. Analogous to
+ * g_timeout_add_seconds() in glib.
+ * <sbr/>This allows UIs to group timers for better power
+ * efficiency. For this reason, @interval may be rounded
+ * by up to a second.
+ * <sbr/>Implementation of this UI op is optional. If it's
+ * not implemented, calls to purple_timeout_add_seconds()
+ * will be serviced by @timeout_add.
+ * <sbr/>See purple_timeout_add_seconds().
*
* An abstraction of an application's mainloop; libpurple will use this to
* watch file descriptors and schedule timed callbacks. If your application
* uses the glib mainloop, there is an implementation of this struct in
- * <filename>libpurple/example/nullclient.c</filename> which you can use verbatim.
+ * <filename>libpurple/example/nullclient.c</filename> which you can use
+ * verbatim.
*/
struct _PurpleEventLoopUiOps
{
- /**
- * Should create a callback timer with an interval measured in
- * milliseconds. The supplied @function should be called every
- * @interval seconds until it returns %FALSE, after which it should not
- * be called again.
- *
- * Analogous to g_timeout_add in glib.
- *
- * Note: On Win32, this function may be called from a thread other than
- * the libpurple thread. You should make sure to detect this situation
- * and to only call "function" from the libpurple thread.
- *
- * @interval: the interval in <emphasis>milliseconds</emphasis> between calls
- * to @function.
- * @data: arbitrary data to be passed to @function at each
- * call.
- * @todo Who is responsible for freeing @data ?
- *
- * Returns: a handle for the timeout, which can be passed to
- * #timeout_remove.
- *
- * @see purple_timeout_add
- **/
+ /* TODO Who is responsible for freeing @data? */
guint (*timeout_add)(guint interval, GSourceFunc function, gpointer data);
- /**
- * Should remove a callback timer. Analogous to g_source_remove in glib.
- * @handle: an identifier for a timeout, as returned by
- * #timeout_add.
- * Returns: %TRUE if the timeout identified by @handle was
- * found and removed.
- * @see purple_timeout_remove
- */
gboolean (*timeout_remove)(guint handle);
- /**
- * Should add an input handler. Analogous to g_io_add_watch_full in
- * glib.
- *
- * @fd: a file descriptor to watch for events
- * @cond: a bitwise OR of events on @fd for which @func
- * should be called.
- * @func: a callback to fire whenever a relevant event on
- * @fd occurs.
- * @user_data: arbitrary data to pass to @fd.
- * Returns: an identifier for this input handler, which can be
- * passed to #input_remove.
- *
- * @see purple_input_add
- */
guint (*input_add)(int fd, PurpleInputCondition cond,
PurpleInputFunction func, gpointer user_data);
- /**
- * Should remove an input handler. Analogous to g_source_remove in glib.
- * @handle: an identifier, as returned by #input_add.
- * Returns: %TRUE if the input handler was found and removed.
- * @see purple_input_remove
- */
gboolean (*input_remove)(guint handle);
-
- /**
- * If implemented, should get the current error status for an input.
- *
- * Implementation of this UI op is optional. Implement it if the UI's
- * sockets or event loop needs to customize determination of socket
- * error status. If unimplemented, <literal>getsockopt(2)</literal> will
- * be used instead.
- *
- * @see purple_input_get_error
- */
int (*input_get_error)(int fd, int *error);
- /**
- * If implemented, should create a callback timer with an interval
- * measured in seconds. Analogous to g_timeout_add_seconds in glib.
- *
- * This allows UIs to group timers for better power efficiency. For
- * this reason, @interval may be rounded by up to a second.
- *
- * Implementation of this UI op is optional. If it's not implemented,
- * calls to purple_timeout_add_seconds() will be serviced by
- * #timeout_add.
- *
- * @see purple_timeout_add_seconds()
- **/
guint (*timeout_add_seconds)(guint interval, GSourceFunc function,
gpointer data);
diff --git a/libpurple/http.c b/libpurple/http.c
--- a/libpurple/http.c
+++ b/libpurple/http.c
@@ -258,24 +258,24 @@ purple_http_connection_set_remove(Purple
static GRegex *purple_http_re_url, *purple_http_re_url_host,
*purple_http_re_rfc1123;
-/**
+/*
* Values: pointers to running PurpleHttpConnection.
*/
static GList *purple_http_hc_list;
-/**
+/*
* Keys: pointers to PurpleConnection.
* Values: GList of pointers to running PurpleHttpConnection.
*/
static GHashTable *purple_http_hc_by_gc;
-/**
+/*
* Keys: pointers to PurpleConnection.
* Values: gboolean TRUE.
*/
static GHashTable *purple_http_cancelling_gc;
-/**
+/*
* Keys: pointers to PurpleHttpConnection.
* Values: pointers to links in purple_http_hc_list.
*/
diff --git a/libpurple/http.h b/libpurple/http.h
--- a/libpurple/http.h
+++ b/libpurple/http.h
@@ -613,10 +613,10 @@ void purple_http_request_set_contents(Pu
/**
* purple_http_request_set_contents_reader:
- * @request: The request.
- * @reader: The reader callback.
- * @contents_size: The size of all contents.
- * @user_data: The user data to pass to the callback function.
+ * @request: The request.
+ * @reader: The reader callback.
+ * @contents_length: The size of all contents.
+ * @user_data: The user data to pass to the callback function.
*
* Sets contents reader for HTTP request, used mainly for possible large
* uploads.
@@ -627,7 +627,7 @@ void purple_http_request_set_contents_re
/**
* purple_http_request_set_response_writer:
* @request: The request.
- * @reader: The writer callback, or NULL to remove existing.
+ * @writer: The writer callback, or %NULL to remove existing.
* @user_data: The user data to pass to the callback function.
*
* Set contents writer for HTTP response.
diff --git a/libpurple/idle.c b/libpurple/idle.c
--- a/libpurple/idle.c
+++ b/libpurple/idle.c
@@ -41,7 +41,7 @@ typedef enum
static PurpleIdleUiOps *idle_ui_ops = NULL;
-/**
+/*
* This is needed for the I'dle Mak'er plugin to work correctly. We
* use it to determine if we're the ones who set our accounts idle
* or if someone else did it (the I'dle Mak'er plugin, for example).
diff --git a/libpurple/imgstore.h b/libpurple/imgstore.h
--- a/libpurple/imgstore.h
+++ b/libpurple/imgstore.h
@@ -52,8 +52,9 @@ G_BEGIN_DECLS
/**
* purple_imgstore_get_type:
*
- * Returns the GType for the PurpleStoredImage boxed structure.
- * TODO Boxing of PurpleStoredImage is a temporary solution to having a GType
+ * Returns: The #GType for the #PurpleStoredImage boxed structure.
+ */
+/* TODO Boxing of PurpleStoredImage is a temporary solution to having a GType
* for stored images. This should rather be a GObject instead of a GBoxed.
*/
GType purple_imgstore_get_type(void);
diff --git a/libpurple/internal.h b/libpurple/internal.h
--- a/libpurple/internal.h
+++ b/libpurple/internal.h
@@ -18,7 +18,7 @@
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
*/
-/**
+/*
* SECTION:internal
* @section_id: libpurple-internal
* @short_description: <filename>internal.h</filename>
@@ -293,10 +293,10 @@ void _purple_conversations_update_cache(
/**
* _purple_statuses_get_primitive_scores:
*
- * Returns the primitive scores array from status.c.
- *
* Note: This function should only be called by
* purple_buddy_presence_compute_score() in presence.c.
+ *
+ * Returns: The primitive scores array from status.c.
*/
int *_purple_statuses_get_primitive_scores(void);
diff --git a/libpurple/keyring.c b/libpurple/keyring.c
--- a/libpurple/keyring.c
+++ b/libpurple/keyring.c
@@ -55,7 +55,7 @@ typedef struct
PurpleKeyring *new_kr;
PurpleKeyring *old_kr;
- /**
+ /*
* We are done when finished is positive and read_outstanding is zero.
*/
gboolean finished;
diff --git a/libpurple/keyring.h b/libpurple/keyring.h
--- a/libpurple/keyring.h
+++ b/libpurple/keyring.h
@@ -399,7 +399,7 @@ purple_keyring_apply_settings(void *noti
/**
* purple_keyring_get_type:
*
- * Returns the GType for the PurpleKeyring boxed structure.
+ * Returns: The #GType for the #PurpleKeyring boxed structure.
*/
GType purple_keyring_get_type(void);
More information about the Commits
mailing list