Fix some gtk-doc warnings till xmlnode.h

17 files changed, 194 insertions, 212 deletions

diff --git a/libpurple/request-datasheet.h b/libpurple/request-datasheet.h
index 17349877a0..8067433770 100644
--- a/libpurple/request-datasheet.h
+++ b/libpurple/request-datasheet.h
@@ -377,9 +377,9 @@ purple_request_datasheet_record_set_string_data(
 
 /**
  * purple_request_datasheet_record_set_image_data:
- * @rec:    The record.
- * @col_no: The column.
- * @data:   The stock identifier of a image.
+ * @rec:      The record.
+ * @col_no:   The column.
+ * @stock_id: The stock identifier of a image.
  *
  * Sets data for a image column of specified record.
  */
diff --git a/libpurple/request.h b/libpurple/request.h
index a2f5b581ef..e8bc09aefb 100644
--- a/libpurple/request.h
+++ b/libpurple/request.h
@@ -64,6 +64,8 @@ typedef struct _PurpleRequestFieldGroup PurpleRequestFieldGroup;
  */
 typedef struct _PurpleRequestCommonParameters PurpleRequestCommonParameters;
 
+typedef struct _PurpleRequestUiOps PurpleRequestUiOps;
+
 #include "account.h"
 
 #define PURPLE_DEFAULT_ACTION_NONE	-1
@@ -133,14 +135,22 @@ typedef void (*PurpleRequestCancelCb)(gpointer);
 
 /**
  * PurpleRequestUiOps:
+ * @request_input:       See purple_request_input().
+ * @request_choice:      See purple_request_choice_varg().
+ * @request_action:      See purple_request_action_varg().
+ * @request_wait:        See purple_request_wait().
+ * @request_wait_update: See purple_request_wait_pulse(),
+ *                           purple_request_wait_progress().
+ * @request_fields:      See purple_request_fields().
+ * @request_file:        See purple_request_file().
+ * @request_folder:      See purple_request_folder().
  *
  * Request UI operations.
  */
-typedef struct
+struct _PurpleRequestUiOps
 {
 	PurpleRequestFeature features;
 
-	/** @see purple_request_input(). */
 	void *(*request_input)(const char *title, const char *primary,
 		const char *secondary, const char *default_value,
 		gboolean multiline, gboolean masked, gchar *hint,
@@ -148,45 +158,35 @@ typedef struct
 		const char *cancel_text, GCallback cancel_cb,
 		PurpleRequestCommonParameters *cpar, void *user_data);
 
-	/** @see purple_request_choice_varg(). */
 	void *(*request_choice)(const char *title, const char *primary,
 		const char *secondary, gpointer default_value,
 		const char *ok_text, GCallback ok_cb, const char *cancel_text,
 		GCallback cancel_cb, PurpleRequestCommonParameters *cpar,
 		void *user_data, va_list choices);
 
-	/** @see purple_request_action_varg(). */
 	void *(*request_action)(const char *title, const char *primary,
 		const char *secondary, int default_action,
 		PurpleRequestCommonParameters *cpar, void *user_data,
 		size_t action_count, va_list actions);
 
-	/** @see purple_request_wait(). */
 	void *(*request_wait)(const char *title, const char *primary,
 		const char *secondary, gboolean with_progress,
 		PurpleRequestCancelCb cancel_cb,
 		PurpleRequestCommonParameters *cpar, void *user_data);
 
-	/**
-	 * @see purple_request_wait_pulse().
-	 * @see purple_request_wait_progress().
-	 */
 	void (*request_wait_update)(void *ui_handle, gboolean pulse,
 		gfloat fraction);
 
-	/** @see purple_request_fields(). */
 	void *(*request_fields)(const char *title, const char *primary,
 		const char *secondary, PurpleRequestFields *fields,
 		const char *ok_text, GCallback ok_cb,
 		const char *cancel_text, GCallback cancel_cb,
 		PurpleRequestCommonParameters *cpar, void *user_data);
 
-	/** @see purple_request_file(). */
 	void *(*request_file)(const char *title, const char *filename,
 		gboolean savedialog, GCallback ok_cb, GCallback cancel_cb,
 		PurpleRequestCommonParameters *cpar, void *user_data);
 
-	/** @see purple_request_folder(). */
 	void *(*request_folder)(const char *title, const char *dirname,
 		GCallback ok_cb, GCallback cancel_cb,
 		PurpleRequestCommonParameters *cpar, void *user_data);
@@ -198,7 +198,7 @@ typedef struct
 	void (*_purple_reserved2)(void);
 	void (*_purple_reserved3)(void);
 	void (*_purple_reserved4)(void);
-} PurpleRequestUiOps;
+};
 
 typedef void (*PurpleRequestInputCb)(void *, const char *);
 
@@ -1243,7 +1243,7 @@ void purple_request_field_int_set_lower_bound(PurpleRequestField *field, int low
  *
  * Sets the upper bound in an integer field.
  */
-void purple_request_field_int_set_upper_bound(PurpleRequestField *field, int lower_bound);
+void purple_request_field_int_set_upper_bound(PurpleRequestField *field, int upper_bound);
 
 /**
  * purple_request_field_int_set_value:
@@ -1897,8 +1897,9 @@ gboolean purple_request_field_email_validator(PurpleRequestField *field,
 /**
  * purple_request_field_alphanumeric_validator:
  * @field: The field.
- * @errmsg: (Optional) destination for error message.
- * @user_data: (Optional) allowed character list (NULL-terminated string).
+ * @errmsg: (allow-none): destination for error message.
+ * @allowed_characters: (allow-none): allowed character list
+ *                      (NULL-terminated string).
  *
  * Validates a field which should contain alphanumeric content.
  *
diff --git a/libpurple/roomlist.c b/libpurple/roomlist.c
index 334d1a2c3c..b7c6238cc2 100644
--- a/libpurple/roomlist.c
+++ b/libpurple/roomlist.c
@@ -31,41 +31,40 @@
 #define PURPLE_ROOMLIST_GET_PRIVATE(obj) \
 	(G_TYPE_INSTANCE_GET_PRIVATE((obj), PURPLE_TYPE_ROOMLIST, PurpleRoomlistPrivate))
 
-/** @copydoc _PurpleRoomlistPrivate */
 typedef struct _PurpleRoomlistPrivate  PurpleRoomlistPrivate;
 
-/**
+/*
  * Private data for a room list.
  */
 struct _PurpleRoomlistPrivate {
-	PurpleAccount *account;  /**< The account this list belongs to. */
-	GList *fields;           /**< The fields.                       */
-	GList *rooms;            /**< The list of rooms.                */
-	gboolean in_progress;    /**< The listing is in progress.       */
+	PurpleAccount *account;  /* The account this list belongs to. */
+	GList *fields;           /* The fields.                       */
+	GList *rooms;            /* The list of rooms.                */
+	gboolean in_progress;    /* The listing is in progress.       */
 
 	/* TODO Remove this and use protocol-specific subclasses. */
-	gpointer proto_data;     /** Protocol private data.             */
+	gpointer proto_data;     /* Protocol private data.             */
 };
 
-/**
+/*
  * Represents a room.
  */
 struct _PurpleRoomlistRoom {
-	PurpleRoomlistRoomType type; /**< The type of room. */
-	gchar *name; /**< The name of the room. */
-	GList *fields; /**< Other fields. */
-	PurpleRoomlistRoom *parent; /**< The parent room, or NULL. */
-	gboolean expanded_once; /**< A flag the UI uses to avoid multiple expand prpl cbs. */
+	PurpleRoomlistRoomType type; /* The type of room. */
+	gchar *name; /* The name of the room. */
+	GList *fields; /* Other fields. */
+	PurpleRoomlistRoom *parent; /* The parent room, or NULL. */
+	gboolean expanded_once; /* A flag the UI uses to avoid multiple expand prpl cbs. */
 };
 
-/**
+/*
  * A field a room might have.
  */
 struct _PurpleRoomlistField {
-	PurpleRoomlistFieldType type; /**< The type of field. */
-	gchar *label; /**< The i18n user displayed name of the field. */
-	gchar *name; /**< The internal name of the field. */
-	gboolean hidden; /**< Hidden? */
+	PurpleRoomlistFieldType type; /* The type of field. */
+	gchar *label; /* The i18n user displayed name of the field. */
+	gchar *name; /* The internal name of the field. */
+	gboolean hidden; /* Hidden? */
 };
 
 /* Room list property enums */
diff --git a/libpurple/roomlist.h b/libpurple/roomlist.h
index 4e908a9183..0dcf9c7700 100644
--- a/libpurple/roomlist.h
+++ b/libpurple/roomlist.h
@@ -117,6 +117,7 @@ struct _PurpleRoomlistUiOps {
 struct _PurpleRoomlist {
 	GObject gparent;
 
+	/*< public >*/
 	gpointer ui_data;
 };
 
@@ -145,7 +146,7 @@ G_BEGIN_DECLS
 /**
  * purple_roomlist_get_type:
  *
- * Returns the GType for the Room List object.
+ * Returns: The #GType for the Room List object.
  */
 GType purple_roomlist_get_type(void);
 
@@ -327,7 +328,7 @@ void purple_roomlist_set_ui_data(PurpleRoomlist *list, gpointer ui_data);
 /**
  * purple_roomlist_room_get_type:
  *
- * Returns the GType for the PurpleRoomlistRoom boxed structure.
+ * Returns: The #GType for the #PurpleRoomlistRoom boxed structure.
  */
 GType purple_roomlist_room_get_type(void);
 
@@ -432,7 +433,7 @@ GList * purple_roomlist_room_get_fields(PurpleRoomlistRoom *room);
 /**
  * purple_roomlist_field_get_type:
  *
- * Returns the GType for the PurpleRoomlistField boxed structure.
+ * Returns: The #GType for the #PurpleRoomlistField boxed structure.
  */
 GType purple_roomlist_field_get_type(void);
 
diff --git a/libpurple/savedstatuses.c b/libpurple/savedstatuses.c
index 3f056324ae..55a1d5a699 100644
--- a/libpurple/savedstatuses.c
+++ b/libpurple/savedstatuses.c
@@ -30,19 +30,19 @@
 #include "util.h"
 #include "xmlnode.h"
 
-/**
+/*
  * The maximum number of transient statuses to save.  This
  * is used during the shutdown process to clean out old
  * transient statuses.
  */
 #define MAX_TRANSIENTS 5
 
-/**
+/*
  * The default message to use when the user becomes auto-away.
  */
 #define DEFAULT_AUTOAWAY_MESSAGE _("I'm not here right now")
 
-/**
+/*
  * The information stores a snap-shot of the statuses of all
  * your accounts.  Basically these are your saved away messages.
  * There is an overall status and message that applies to
@@ -59,14 +59,14 @@ struct _PurpleSavedStatus
 	PurpleStatusPrimitive type;
 	char *message;
 
-	/** The timestamp when this saved status was created. This must be unique. */
+	/* The timestamp when this saved status was created. This must be unique. */
 	time_t creation_time;
 
 	time_t lastused;
 
 	unsigned int usage_count;
 
-	GList *substatuses;      /**< A list of PurpleSavedStatusSub's. */
+	GList *substatuses;      /* A list of PurpleSavedStatusSub's. */
 };
 
 /*
@@ -151,7 +151,7 @@ set_creation_time(PurpleSavedStatus *status, time_t creation_time)
 						status);
 }
 
-/**
+/*
  * A magic number is calculated for each status, and then the
  * statuses are ordered by the magic number.  The magic number
  * is the date the status was last used offset by one day for
@@ -178,7 +178,7 @@ saved_statuses_sort_func(gconstpointer a, gconstpointer b)
 	return 0;
 }
 
-/**
+/*
  * Transient statuses are added and removed automatically by
  * Purple.  If they're not used for a certain length of time then
  * they'll expire and be automatically removed.  This function
@@ -419,7 +419,7 @@ parse_substatus(PurpleXmlNode *substatus)
 	return ret;
 }
 
-/**
+/*
  * Parse a saved status and add it to the saved_statuses linked list.
  *
  * Here's an example of the XML for a saved status:
@@ -515,11 +515,13 @@ parse_status(PurpleXmlNode *status)
 	return ret;
 }
 
-/**
+/*
+ * load_statuses:
+ *
  * Read the saved statuses from a file in the Purple user dir.
  *
- * @return TRUE on success, FALSE on failure (if the file can not
- *         be opened, or if it contains invalid XML).
+ * Returns: TRUE on success, FALSE on failure (if the file can not
+ *          be opened, or if it contains invalid XML).
  */
 static void
 load_statuses(void)
diff --git a/libpurple/savedstatuses.h b/libpurple/savedstatuses.h
index 5384581706..6d1f23bb93 100644
--- a/libpurple/savedstatuses.h
+++ b/libpurple/savedstatuses.h
@@ -75,8 +75,9 @@ G_BEGIN_DECLS
 /**
  * purple_savedstatus_get_g_type:
  *
- * Returns the GType for the PurpleSavedStatus boxed structure.
- * TODO Boxing of PurpleSavedStatus is a temporary solution to having a GType
+ * Returns: The #GType for the #PurpleSavedStatus boxed structure.
+ */
+/* TODO Boxing of PurpleSavedStatus is a temporary solution to having a GType
  *      for saved statuses. This should rather be a GObject instead of a GBoxed.
  */
 GType purple_savedstatus_get_g_type(void);
diff --git a/libpurple/signals.h b/libpurple/signals.h
index 51e00ce69d..ab3899f0b5 100644
--- a/libpurple/signals.h
+++ b/libpurple/signals.h
@@ -50,7 +50,7 @@ G_BEGIN_DECLS
  *
  * The priority of a signal connected using purple_signal_connect().
  *
- * @see purple_signal_connect_priority()
+ * See purple_signal_connect_priority()
  */
 #define PURPLE_SIGNAL_PRIORITY_DEFAULT     0
 
@@ -61,7 +61,7 @@ G_BEGIN_DECLS
  * <emphasis>last</emphasis>.  (This is highest as in numerical value, not as in
  * order of importance.)
  *
- * @see purple_signal_connect_priority().
+ * See purple_signal_connect_priority().
  */
 #define PURPLE_SIGNAL_PRIORITY_HIGHEST  9999
 
@@ -72,7 +72,7 @@ G_BEGIN_DECLS
  * <emphasis>first</emphasis>.  (This is lowest as in numerical value, not as in
  * order of importance.)
  *
- * @see purple_signal_connect_priority().
+ * See purple_signal_connect_priority().
  */
 #define PURPLE_SIGNAL_PRIORITY_LOWEST  -9999
 
@@ -88,7 +88,7 @@ G_BEGIN_DECLS
  * Registers a signal in an instance.
  *
  * Returns: The signal ID local to that instance, or 0 if the signal
- *         couldn't be registered.
+ *          couldn't be registered.
  */
 gulong purple_signal_register(void *instance, const char *signal,
 							PurpleSignalMarshalFunc marshal,
@@ -113,13 +113,14 @@ void purple_signals_unregister_by_instance(void *instance);
 
 /**
  * purple_signal_get_types:
- * @instance:    The instance the signal is registered to.
- * @signal:      The signal.
- * @ret_type:    The return type.
- * @num_values:  The returned number of parameters.
- * @param_types: The returned list of parameter types.
- *
- * Returns a list of value types used for a signal.
+ * @instance:           The instance the signal is registered to.
+ * @signal:             The signal.
+ * @ret_type: (out):    The return type.
+ * @num_values: (out):  The returned number of parameters.
+ * @param_types: (out): The returned list of parameter types.
+ *
+ * Outputs a list of value types used for a signal through the @ret_type,
+ * @num_values and @param_types out parameters.
  */
 void purple_signal_get_types(void *instance, const char *signal,
 							GType *ret_type, int *num_values,
@@ -142,9 +143,9 @@ void purple_signal_get_types(void *instance, const char *signal,
  * Take care not to register a handler function twice. Purple will
  * not correct any mistakes for you in this area.
  *
- * Returns: The signal handler ID.
+ * See purple_signal_disconnect()
  *
- * @see purple_signal_disconnect()
+ * Returns: The signal handler ID.
  */
 gulong purple_signal_connect_priority(void *instance, const char *signal,
 	void *handle, PurpleCallback func, void *data, int priority);
@@ -163,9 +164,9 @@ gulong purple_signal_connect_priority(void *instance, const char *signal,
  * Take care not to register a handler function twice. Purple will
  * not correct any mistakes for you in this area.
  *
- * Returns: The signal handler ID.
+ * See purple_signal_disconnect()
  *
- * @see purple_signal_disconnect()
+ * Returns: The signal handler ID.
  */
 gulong purple_signal_connect(void *instance, const char *signal,
 	void *handle, PurpleCallback func, void *data);
@@ -190,9 +191,9 @@ gulong purple_signal_connect(void *instance, const char *signal,
  * Take care not to register a handler function twice. Purple will
  * not correct any mistakes for you in this area.
  *
- * Returns: The signal handler ID.
+ * See purple_signal_disconnect()
  *
- * @see purple_signal_disconnect()
+ * Returns: The signal handler ID.
  */
 gulong purple_signal_connect_priority_vargs(void *instance, const char *signal,
 	void *handle, PurpleCallback func, void *data, int priority);
@@ -214,9 +215,9 @@ gulong purple_signal_connect_priority_vargs(void *instance, const char *signal,
  * Take care not to register a handler function twice. Purple will
  * not correct any mistakes for you in this area.
  *
- * Returns: The signal handler ID.
+ * See purple_signal_disconnect()
  *
- * @see purple_signal_disconnect()
+ * Returns: The signal handler ID.
  */
 gulong purple_signal_connect_vargs(void *instance, const char *signal,
 	void *handle, PurpleCallback func, void *data);
@@ -230,7 +231,7 @@ gulong purple_signal_connect_vargs(void *instance, const char *signal,
  *
  * Disconnects a signal handler from a signal on an object.
  *
- * @see purple_signal_connect()
+ * See purple_signal_connect()
  */
 void purple_signal_disconnect(void *instance, const char *signal,
 							void *handle, PurpleCallback func);
@@ -250,8 +251,7 @@ void purple_signals_disconnect_by_handle(void *handle);
  *
  * Emits a signal.
  *
- * @see purple_signal_connect()
- * @see purple_signal_disconnect()
+ * See purple_signal_connect(), purple_signal_disconnect()
  */
 void purple_signal_emit(void *instance, const char *signal, ...);
 
@@ -263,8 +263,7 @@ void purple_signal_emit(void *instance, const char *signal, ...);
  *
  * Emits a signal, using a va_list of arguments.
  *
- * @see purple_signal_connect()
- * @see purple_signal_disconnect()
+ * See purple_signal_connect(), purple_signal_disconnect()
  */
 void purple_signal_emit_vargs(void *instance, const char *signal, va_list args);
 
diff --git a/libpurple/sslconn.h b/libpurple/sslconn.h
index 0478d01753..7d8751553f 100644
--- a/libpurple/sslconn.h
+++ b/libpurple/sslconn.h
@@ -46,6 +46,7 @@ typedef enum
 #define PURPLE_SSL_DEFAULT_PORT 443
 
 typedef struct _PurpleSslConnection PurpleSslConnection;
+typedef struct _PurpleSslOps PurpleSslOps;
 
 typedef void (*PurpleSslInputFunction)(gpointer, PurpleSslConnection *,
 									 PurpleInputCondition);
@@ -90,60 +91,51 @@ struct _PurpleSslConnection
 
 /**
  * PurpleSslOps:
+ * @init: Initializes the SSL system provided. See purple_ssl_init().
+ *        <sbr/>Returns: %TRUE if initialization succeeded
+ * @uninit: Unloads the SSL system. Inverse of PurpleSslOps::init.
+ *          See purple_ssl_uninit().
+ * @connectfunc: Sets up the SSL connection for a #PurpleSslConnection once the
+ *               TCP connection has been established. See purple_ssl_connect().
+ * @close: Destroys the internal data of the SSL connection provided. Freeing
+ *         @gsc itself is left to purple_ssl_close().
+ * @read: Reads data from a connection (like POSIX read()).
+ *        See purple_ssl_read().
+ *        <sbr/>@gsc:    Connection context
+ *        <sbr/>@data:   Pointer to buffer to drop data into
+ *        <sbr/>@len:    Maximum number of bytes to read
+ *        <sbr/>Returns: Number of bytes actually written into @data
+ *                       (which may be less than @len), or <0 on error
+ * @write: Writes data to a connection (like POSIX send()).
+ *         See purple_ssl_write().
+ *         <sbr/>@gsc:    Connection context
+ *         <sbr/>@data:   Data buffer to send data from
+ *         <sbr/>@len:    Number of bytes to send from buffer
+ *         <sbr/>Returns: The number of bytes written to @data (may be less than
+ *                        @len) or <0 on error
+ * @get_peer_certificates: Obtains the certificate chain provided by the peer.
+ *                         See #PurpleCertificate.
+ *                         <sbr/>@gsc:    Connection context
+ *                         <sbr/>Returns: A newly allocated list containing the
+ *                                        certificates the peer provided.
  *
  * SSL implementation operations structure.
  *
- * Every SSL implementation must provide all of these and register it via purple_ssl_set_ops()
+ * Every SSL implementation must provide all of these and register it via
+ * purple_ssl_set_ops().
  * These should not be called directly! Instead, use the purple_ssl_* functions.
  */
-typedef struct
+struct _PurpleSslOps
 {
-	/** Initializes the SSL system provided.
-	 *  Returns: %TRUE if initialization succeeded
-	 *  @see purple_ssl_init
-	 */
 	gboolean (*init)(void);
-	/** Unloads the SSL system. Inverse of PurpleSslOps::init.
-	 *  @see purple_ssl_uninit
-	 */
 	void (*uninit)(void);
-	/** Sets up the SSL connection for a #PurpleSslConnection once
-	 *  the TCP connection has been established
-	 *  @see purple_ssl_connect
-	 */
 	void (*connectfunc)(PurpleSslConnection *gsc);
-	/** Destroys the internal data of the SSL connection provided.
-	 *  Freeing gsc itself is left to purple_ssl_close()
-	 *  @see purple_ssl_close
-	 */
 	void (*close)(PurpleSslConnection *gsc);
-	/** Reads data from a connection (like POSIX read())
-	 * @gsc:   Connection context
-	 * @data:  Pointer to buffer to drop data into
-	 * @len:   Maximum number of bytes to read
-	 * Returns:      Number of bytes actually written into @data (which may be
-	 *              less than @len), or <0 on error
-	 * @see purple_ssl_read
-	*/
 	size_t (*read)(PurpleSslConnection *gsc, void *data, size_t len);
-	/** Writes data to a connection (like POSIX send())
-	* @gsc:    Connection context
-	* @data:   Data buffer to send data from
-	* @len:    Number of bytes to send from buffer
-	* Returns:       The number of bytes written to @data (may be less than
-	*               @len) or <0 on error
-	* @see purple_ssl_write
-	*/
 	size_t (*write)(PurpleSslConnection *gsc, const void *data, size_t len);
-	/** Obtains the certificate chain provided by the peer
-	 *
-	 * @gsc:   Connection context
-	 * Returns:      A newly allocated list containing the certificates
-	 *              the peer provided.
-	 * @see PurpleCertificate
-	 * @todo        Decide whether the ordering of certificates in this
-	 *              list can be guaranteed.
-	 */
+
+	/* TODO Decide whether the ordering of certificates in this list can be
+	        guaranteed. */
 	GList * (* get_peer_certificates)(PurpleSslConnection * gsc);
 
 	/*< private >*/
@@ -151,7 +143,7 @@ typedef struct
 	void (*_purple_reserved2)(void);
 	void (*_purple_reserved3)(void);
 	void (*_purple_reserved4)(void);
-} PurpleSslOps;
+};
 
 G_BEGIN_DECLS
 
diff --git a/libpurple/status.c b/libpurple/status.c
index 9e52fd5012..287050ed7a 100644
--- a/libpurple/status.c
+++ b/libpurple/status.c
@@ -32,10 +32,9 @@
 #define PURPLE_STATUS_GET_PRIVATE(obj) \
 	(G_TYPE_INSTANCE_GET_PRIVATE((obj), PURPLE_TYPE_STATUS, PurpleStatusPrivate))
 
-/** @copydoc _PurpleStatusPrivate */
 typedef struct _PurpleStatusPrivate  PurpleStatusPrivate;
 
-/**
+/*
  * A type of status.
  */
 struct _PurpleStatusType
@@ -52,7 +51,7 @@ struct _PurpleStatusType
 	GList *attrs;
 };
 
-/**
+/*
  * A status attribute.
  */
 struct _PurpleStatusAttribute
@@ -62,7 +61,7 @@ struct _PurpleStatusAttribute
 	GValue *value_type;
 };
 
-/**
+/*
  * Private data for PurpleStatus
  */
 struct _PurpleStatusPrivate
diff --git a/libpurple/status.h b/libpurple/status.h
index 9e520d88ad..6c1e2df66a 100644
--- a/libpurple/status.h
+++ b/libpurple/status.h
@@ -209,7 +209,7 @@ PurpleStatusPrimitive purple_primitive_get_type_from_id(const char *id);
 /**
  * purple_status_type_get_type:
  *
- * Returns the GType for the PurpleStatusType boxed structure.
+ * Returns: The #GType for the #PurpleStatusType boxed structure.
  */
 GType purple_status_type_get_type(void);
 
@@ -427,7 +427,7 @@ const PurpleStatusType *purple_status_type_find_with_id(GList *status_types,
 /**
  * purple_status_attribute_get_type:
  *
- * Returns the GType for the PurpleStatusAttribute boxed structure.
+ * Returns: The #GType for the #PurpleStatusAttribute boxed structure.
  */
 GType purple_status_attribute_get_type(void);
 
@@ -492,7 +492,7 @@ GValue *purple_status_attribute_get_value(const PurpleStatusAttribute *attr);
 /**
  * purple_mood_get_type:
  *
- * Returns the GType for the PurpleMood boxed structure.
+ * Returns: The #GType for the #PurpleMood boxed structure.
  */
 GType purple_mood_get_type(void);
 
@@ -506,7 +506,7 @@ GType purple_mood_get_type(void);
 /**
  * purple_status_get_type:
  *
- * Returns the GType for the Status object.
+ * Returns: The #GType for the Status object.
  */
 GType purple_status_get_type(void);
 
diff --git a/libpurple/stringref.c b/libpurple/stringref.c
index b1e720ac51..8ec1637b9f 100644
--- a/libpurple/stringref.c
+++ b/libpurple/stringref.c
@@ -29,7 +29,7 @@
 #include "eventloop.h"
 #include "stringref.h"
 
-/**
+/*
  * The internal representation of a stringref.
  *
  * @note For this structure to be useful, the string contained within
@@ -37,14 +37,14 @@
  * directly!
  */
 struct _PurpleStringref {
-	guint32 ref;	/**< The reference count of this string.
+	guint32 ref;	/* The reference count of this string.
 					 *   Note that reference counts are only
 					 *   31 bits, and the high-order bit
 					 *   indicates whether this string is up
 					 *   for GC at the next idle handler...
 					 *   But you aren't going to touch this
 					 *   anyway, right? */
-	char value[1];	/**< The string contained in this ref.
+	char value[1];	/* The string contained in this ref.
 					 *   Notice that it is simply "hanging
 					 *   off the end" of the ref ... this
 					 *   is to save an allocation. */
diff --git a/libpurple/stun.c b/libpurple/stun.c
index fc96b0d21d..b5186d8c2f 100644
--- a/libpurple/stun.c
+++ b/libpurple/stun.c
@@ -386,8 +386,8 @@ PurpleStunNatDiscovery *purple_stun_discover(StunCallback cb) {
 	if(nattype.status != PURPLE_STUN_STATUS_UNDISCOVERED) {
 		gboolean use_cached_result = TRUE;
 
-		/** Deal with the server name having changed since we did the
-		    lookup */
+		/* Deal with the server name having changed since we did the
+		   lookup */
 		if (servername && strlen(servername) > 1
 				&& !purple_strequal(servername, nattype.servername)) {
 			use_cached_result = FALSE;
diff --git a/libpurple/util.h b/libpurple/util.h
index 63c9438da3..153319b92d 100644
--- a/libpurple/util.h
+++ b/libpurple/util.h
@@ -172,8 +172,8 @@ void purple_menu_action_set_children(PurpleMenuAction *act, GList *children);
 
 /**
  * purple_menu_action_set_stock_icon:
- * @act:    The menu action.
- * @strock: The stock icon identifier.
+ * @act:   The menu action.
+ * @stock: The stock icon identifier.
  *
  * Sets the icon for the PurpleMenuAction.
  */
diff --git a/libpurple/whiteboard.h b/libpurple/whiteboard.h
index d6a55b9342..3fa4d0c98b 100644
--- a/libpurple/whiteboard.h
+++ b/libpurple/whiteboard.h
@@ -95,12 +95,13 @@ struct _PurpleWhiteboardPrplOps
  * @ui_data: The UI data associated with this whiteboard. This is a convenience
  *           field provided to the UIs -- it is not used by the libpurple core.
  *
- * A PurpleWhiteboard
+ * A Whiteboard
  */
 struct _PurpleWhiteboard
 {
 	GObject gparent;
 
+	/*< public >*/
 	gpointer ui_data;
 };
 
@@ -129,7 +130,7 @@ G_BEGIN_DECLS
 /**
  * purple_whiteboard_get_type:
  *
- * Returns the GType for the PurpleWhiteboard object.
+ * Returns: The #GType for the #PurpleWhiteboard object.
  */
 GType purple_whiteboard_get_type(void);
 
diff --git a/libpurple/xfer.c b/libpurple/xfer.c
index 9a10933ca9..d67bee69ed 100644
--- a/libpurple/xfer.c
+++ b/libpurple/xfer.c
@@ -39,48 +39,47 @@
 #define PURPLE_XFER_GET_PRIVATE(obj) \
 	(G_TYPE_INSTANCE_GET_PRIVATE((obj), PURPLE_TYPE_XFER, PurpleXferPrivate))
 
-/** @copydoc _PurpleXferPrivate */
 typedef struct _PurpleXferPrivate  PurpleXferPrivate;
 
 static PurpleXferUiOps *xfer_ui_ops = NULL;
 static GList *xfers;
 
-/** Private data for a file transfer */
+/* Private data for a file transfer */
 struct _PurpleXferPrivate {
-	PurpleXferType type;         /**< The type of transfer.               */
+	PurpleXferType type;         /* The type of transfer.               */
 
-	PurpleAccount *account;      /**< The account.                        */
+	PurpleAccount *account;      /* The account.                        */
 
-	char *who;                   /**< The person on the other end of the
-	                                  transfer.                           */
+	char *who;                   /* The person on the other end of the
+	                                transfer.                           */
 
-	char *message;               /**< A message sent with the request     */
-	char *filename;              /**< The name sent over the network.     */
-	char *local_filename;        /**< The name on the local hard drive.   */
-	goffset size;                /**< The size of the file.               */
+	char *message;               /* A message sent with the request     */
+	char *filename;              /* The name sent over the network.     */
+	char *local_filename;        /* The name on the local hard drive.   */
+	goffset size;                /* The size of the file.               */
 
-	FILE *dest_fp;               /**< The destination file pointer.       */
+	FILE *dest_fp;               /* The destination file pointer.       */
 
-	char *remote_ip;             /**< The remote IP address.              */
-	guint16 local_port;          /**< The local port.                     */
-	guint16 remote_port;         /**< The remote port.                    */
+	char *remote_ip;             /* The remote IP address.              */
+	guint16 local_port;          /* The local port.                     */
+	guint16 remote_port;         /* The remote port.                    */
 
-	int fd;                      /**< The socket file descriptor.         */
-	int watcher;                 /**< Watcher.                            */
+	int fd;                      /* The socket file descriptor.         */
+	int watcher;                 /* Watcher.                            */
 
-	goffset bytes_sent;          /**< The number of bytes sent.           */
-	goffset bytes_remaining;     /**< The number of bytes remaining.      */
-	time_t start_time;           /**< When the transfer of data began.    */
-	time_t end_time;             /**< When the transfer of data ended.    */
+	goffset bytes_sent;          /* The number of bytes sent.           */
+	goffset bytes_remaining;     /* The number of bytes remaining.      */
+	time_t start_time;           /* When the transfer of data began.    */
+	time_t end_time;             /* When the transfer of data ended.    */
 
-	size_t current_buffer_size;  /**< This gradually increases for fast
-	                                   network connections.               */
+	size_t current_buffer_size;  /* This gradually increases for fast
+	                                 network connections.               */
 
-	PurpleXferStatus status;     /**< File Transfer's status.             */
+	PurpleXferStatus status;     /* File Transfer's status.             */
 
-	/** I/O operations, which should be set by the prpl using
-	 *  purple_xfer_set_init_fnc() and friends.  Setting #init is
-	 *  mandatory; all others are optional.
+	/* I/O operations, which should be set by the prpl using
+	 * purple_xfer_set_init_fnc() and friends.  Setting #init is
+	 * mandatory; all others are optional.
 	 */
 	struct
 	{
@@ -95,10 +94,10 @@ struct _PurpleXferPrivate {
 		void (*ack)(PurpleXfer *xfer, const guchar *buffer, size_t size);
 	} ops;
 
-	PurpleXferUiOps *ui_ops;     /**< UI-specific operations.             */
+	PurpleXferUiOps *ui_ops;     /* UI-specific operations.             */
 
 	/* TODO Remove this and use protocol-specific subclasses. */
-	void *proto_data;            /**< prpl-specific data.                 */
+	void *proto_data;            /* prpl-specific data.                 */
 
 	/*
 	 * Used to moderate the file transfer when either the read/write ui_ops are
@@ -114,7 +113,7 @@ struct _PurpleXferPrivate {
 	/* TODO: Should really use a PurpleCircBuffer for this. */
 	GByteArray *buffer;
 
-	gpointer thumbnail_data;     /**< thumbnail image */
+	gpointer thumbnail_data;     /* thumbnail image */
 	gsize thumbnail_size;
 	gchar *thumbnail_mimetype;
 };
diff --git a/libpurple/xfer.h b/libpurple/xfer.h
index 36d57d4d59..11b402bc2c 100644
--- a/libpurple/xfer.h
+++ b/libpurple/xfer.h
@@ -42,6 +42,8 @@
 typedef struct _PurpleXfer PurpleXfer;
 typedef struct _PurpleXferClass PurpleXferClass;
 
+typedef struct _PurpleXferUiOps PurpleXferUiOps;
+
 #include <glib.h>
 #include <stdio.h>
 
@@ -90,13 +92,40 @@ typedef enum
 
 /**
  * PurpleXferUiOps:
+ * @ui_write: UI op to write data received from the protocol. The UI must deal
+ *            with the entire buffer and return size, or it is treated as an
+ *            error.
+ *            <sbr/>@xfer:   The file transfer structure
+ *            <sbr/>@buffer: The buffer to write
+ *            <sbr/>@size:   The size of the buffer
+ *            <sbr/>Returns: size if the write was successful, or a value
+ *                           between 0 and size on error.
+ * @ui_read: UI op to read data to send to the protocol for a file transfer.
+ *           <sbr/>@xfer:   The file transfer structure
+ *           <sbr/>@buffer: A pointer to a buffer. The UI must allocate this
+ *                          buffer. libpurple will free the data.
+ *           <sbr/>@size:   The maximum amount of data to put in the buffer.
+ *           <sbr/>Returns: The amount of data in the buffer, 0 if nothing is
+ *                          available, and a negative value if an error occurred
+ *                          and the transfer should be cancelled (libpurple will
+ *                          cancel).
+ * @data_not_sent: Op to notify the UI that not all the data read in was
+ *                 written. The UI should re-enqueue this data and return it the
+ *                 next time read is called.
+ *                 <sbr/>This <emphasis>MUST</emphasis> be implemented if read
+ *                 and write are implemented.
+ *                 <sbr/>@xfer:   The file transfer structure
+ *                 <sbr/>@buffer: A pointer to the beginning of the unwritten
+ *                                data.
+ *                 <sbr/>@size:   The amount of unwritten data.
+ * @add_thumbnail: Op to create a thumbnail image for a file transfer
  *
  * File transfer UI operations.
  *
  * Any UI representing a file transfer must assign a filled-out
  * PurpleXferUiOps structure to the purple_xfer.
  */
-typedef struct
+struct _PurpleXferUiOps
 {
 	void (*new_xfer)(PurpleXfer *xfer);
 	void (*destroy)(PurpleXfer *xfer);
@@ -104,53 +133,11 @@ typedef struct
 	void (*update_progress)(PurpleXfer *xfer, double percent);
 	void (*cancel_local)(PurpleXfer *xfer);
 	void (*cancel_remote)(PurpleXfer *xfer);
-
-	/**
-	 * UI op to write data received from the protocol. The UI must deal with the
-	 * entire buffer and return size, or it is treated as an error.
-	 *
-	 * @xfer:    The file transfer structure
-	 * @buffer:  The buffer to write
-	 * @size:    The size of the buffer
-	 *
-	 * Returns: size if the write was successful, or a value between 0 and
-	 *         size on error.
-	 */
 	gssize (*ui_write)(PurpleXfer *xfer, const guchar *buffer, gssize size);
-
-	/**
-	 * UI op to read data to send to the protocol for a file transfer.
-	 *
-	 * @xfer:    The file transfer structure
-	 * @buffer:  A pointer to a buffer. The UI must allocate this buffer.
-	 *                libpurple will free the data.
-	 * @size:    The maximum amount of data to put in the buffer.
-	 *
-	 * Returns: The amount of data in the buffer, 0 if nothing is available,
-	 *          and a negative value if an error occurred and the transfer
-	 *          should be cancelled (libpurple will cancel).
-	 */
 	gssize (*ui_read)(PurpleXfer *xfer, guchar **buffer, gssize size);
-
-	/**
-	 * Op to notify the UI that not all the data read in was written. The UI
-	 * should re-enqueue this data and return it the next time read is called.
-	 *
-	 * This MUST be implemented if read and write are implemented.
-	 *
-	 * @xfer:    The file transfer structure
-	 * @buffer:  A pointer to the beginning of the unwritten data.
-	 * @size:    The amount of unwritten data.
-	 */
 	void (*data_not_sent)(PurpleXfer *xfer, const guchar *buffer, gsize size);
-
-	/**
-	 * Op to create a thumbnail image for a file transfer
-	 *
-	 * @xfer:   The file transfer structure
-	 */
 	void (*add_thumbnail)(PurpleXfer *xfer, const gchar *formats);
-} PurpleXferUiOps;
+};
 
 /**
  * PurpleXfer:
@@ -164,6 +151,7 @@ struct _PurpleXfer
 {
 	GObject gparent;
 
+	/*< public >*/
 	gpointer ui_data;
 };
 
@@ -193,7 +181,7 @@ G_BEGIN_DECLS
 /**
  * purple_xfer_get_type:
  *
- * Returns the GType for the PurpleXfer object.
+ * Returns: The #GType for the #PurpleXfer object.
  */
 GType purple_xfer_get_type(void);
 
diff --git a/libpurple/xmlnode.h b/libpurple/xmlnode.h
index 3f20eedf47..b359a443ac 100644
--- a/libpurple/xmlnode.h
+++ b/libpurple/xmlnode.h
@@ -86,7 +86,7 @@ G_BEGIN_DECLS
 /**
  * purple_xmlnode_get_type:
  *
- * Returns the GType for the PurpleXmlNode boxed structure.
+ * Returns: The #GType for the #PurpleXmlNode boxed structure.
  */
 GType purple_xmlnode_get_type(void);