--- a/libpurple/util.h Fri Jan 31 17:56:27 2014 +0530
+++ b/libpurple/util.h Fri Jan 31 18:14:33 2014 +0530
@@ -67,13 +67,13 @@
/**
* Creates a new PurpleMenuAction.
*
- * @param label The text label to display for this action.
- * @param callback The function to be called when the action is used on
+ * @label: The text label to display for this action.
+ * @callback: The function to be called when the action is used on
* the selected item.
- * @param data Additional data to be passed to the callback.
- * @param children A GList of PurpleMenuActions to be added as a submenu
+ * @data: Additional data to be passed to the callback.
+ * @children: A GList of PurpleMenuActions to be added as a submenu
* of the action.
- * @return The PurpleMenuAction.
+ * Returns: The PurpleMenuAction.
*/
PurpleMenuAction *purple_menu_action_new(const char *label, PurpleCallback callback,
gpointer data, GList *children);
@@ -81,83 +81,83 @@
/**
* Frees a PurpleMenuAction
*
- * @param act The PurpleMenuAction to free.
+ * @act: The PurpleMenuAction to free.
*/
void purple_menu_action_free(PurpleMenuAction *act);
/**
* Returns the label of the PurpleMenuAction.
*
- * @param act The PurpleMenuAction.
+ * @act: The PurpleMenuAction.
*
- * @return The label string.
+ * Returns: The label string.
*/
char * purple_menu_action_get_label(const PurpleMenuAction *act);
/**
* Returns the callback of the PurpleMenuAction.
*
- * @param act The PurpleMenuAction.
+ * @act: The PurpleMenuAction.
*
- * @return The callback function.
+ * Returns: The callback function.
*/
PurpleCallback purple_menu_action_get_callback(const PurpleMenuAction *act);
/**
* Returns the data stored in the PurpleMenuAction.
*
- * @param act The PurpleMenuAction.
+ * @act: The PurpleMenuAction.
*
- * @return The data.
+ * Returns: The data.
*/
gpointer purple_menu_action_get_data(const PurpleMenuAction *act);
/**
* Returns the children of the PurpleMenuAction.
*
- * @param act The PurpleMenuAction.
+ * @act: The PurpleMenuAction.
*
- * @return The GList of children.
+ * Returns: The GList of children.
*/
GList* purple_menu_action_get_children(const PurpleMenuAction *act);
/**
* Set the label to the PurpleMenuAction.
*
- * @param act The menu action.
- * @param label The label for the menu action.
+ * @act: The menu action.
+ * @label: The label for the menu action.
*/
void purple_menu_action_set_label(PurpleMenuAction *act, char *label);
/**
* Set the callback that will be used by the PurpleMenuAction.
*
- * @param act The menu action.
- * @param callback The callback.
+ * @act: The menu action.
+ * @callback: The callback.
*/
void purple_menu_action_set_callback(PurpleMenuAction *act, PurpleCallback callback);
/**
* Set the label to the PurpleMenuAction.
*
- * @param act The menu action.
- * @param data The data used by this PurpleMenuAction
+ * @act: The menu action.
+ * @data: The data used by this PurpleMenuAction
*/
void purple_menu_action_set_data(PurpleMenuAction *act, gpointer data);
/**
* Set the children of the PurpleMenuAction.
*
- * @param act The menu action.
- * @param children The PurpleMenuAtion children
+ * @act: The menu action.
+ * @children: The PurpleMenuAtion children
*/
void purple_menu_action_set_children(PurpleMenuAction *act, GList *children);
/**
* Sets the icon for the PurpleMenuAction.
*
- * @param act The menu action.
- * @param strock The stock icon identifier.
+ * @act: The menu action.
+ * @strock: The stock icon identifier.
*/
void purple_menu_action_set_stock_icon(PurpleMenuAction *act,
const gchar *stock);
@@ -165,9 +165,9 @@
/**
* Gets the stock icon of the PurpleMenuAction.
*
- * @param act The menu action.
+ * @act: The menu action.
*
- * @return The stock icon identifier.
+ * Returns: The stock icon identifier.
*/
const gchar *
purple_menu_action_get_stock_icon(PurpleMenuAction *act);
@@ -175,9 +175,9 @@
/**
* Set the appropriate presence values for the currently playing song.
*
- * @param title The title of the song, @c NULL to unset the value.
- * @param artist The artist of the song, can be @c NULL.
- * @param album The album of the song, can be @c NULL.
+ * @title: The title of the song, %NULL to unset the value.
+ * @artist: The artist of the song, can be %NULL.
+ * @album: The album of the song, can be %NULL.
*/
void purple_util_set_current_song(const char *title, const char *artist,
const char *album);
@@ -185,12 +185,12 @@
/**
* Format song information.
*
- * @param title The title of the song, @c NULL to unset the value.
- * @param artist The artist of the song, can be @c NULL.
- * @param album The album of the song, can be @c NULL.
- * @param unused Currently unused, must be @c NULL.
+ * @title: The title of the song, %NULL to unset the value.
+ * @artist: The artist of the song, can be %NULL.
+ * @album: The album of the song, can be %NULL.
+ * @unused: Currently unused, must be %NULL.
*
- * @return The formatted string. The caller must g_free the returned string.
+ * Returns: The formatted string. The caller must g_free the returned string.
*/
char * purple_util_format_song_info(const char *title, const char *artist,
const char *album, gpointer unused);
@@ -220,10 +220,10 @@
/**
* Converts a chunk of binary data to its base-16 equivalent.
*
- * @param data The data to convert.
- * @param len The length of the data.
+ * @data: The data to convert.
+ * @len: The length of the data.
*
- * @return The base-16 string in the ASCII encoding. Must be
+ * Returns: The base-16 string in the ASCII encoding. Must be
* g_free'd when no longer needed.
*
* @see purple_base16_decode()
@@ -234,14 +234,14 @@
* Converts an ASCII string of base-16 encoded data to
* the binary equivalent.
*
- * @param str The base-16 string to convert to raw data.
- * @param ret_len The length of the returned data. You can
+ * @str: The base-16 string to convert to raw data.
+ * @ret_len: The length of the returned data. You can
* pass in NULL if you're sure that you know
* the length of the decoded data, or if you
* know you'll be able to use strlen to
* determine the length, etc.
*
- * @return The raw data. Must be g_free'd when no longer needed.
+ * Returns: The raw data. Must be g_free'd when no longer needed.
*
* @see purple_base16_encode()
*/
@@ -253,10 +253,10 @@
*
* Example output: 01:23:45:67:89:AB:CD:EF
*
- * @param data The data to convert.
- * @param len The length of the data.
+ * @data: The data to convert.
+ * @len: The length of the data.
*
- * @return The base-16 string in the ASCII chunked encoding. Must be
+ * Returns: The base-16 string in the ASCII chunked encoding. Must be
* g_free'd when no longer needed.
*/
gchar *purple_base16_encode_chunked(const guchar *data, gsize len);
@@ -272,10 +272,10 @@
/**
* Converts a chunk of binary data to its base-64 equivalent.
*
- * @param data The data to convert.
- * @param len The length of the data.
+ * @data: The data to convert.
+ * @len: The length of the data.
*
- * @return The base-64 string in the ASCII encoding. Must be
+ * Returns: The base-64 string in the ASCII encoding. Must be
* g_free'd when no longer needed.
*
* @see purple_base64_decode()
@@ -286,14 +286,14 @@
* Converts an ASCII string of base-64 encoded data to
* the binary equivalent.
*
- * @param str The base-64 string to convert to raw data.
- * @param ret_len The length of the returned data. You can
+ * @str: The base-64 string to convert to raw data.
+ * @ret_len: The length of the returned data. You can
* pass in NULL if you're sure that you know
* the length of the decoded data, or if you
* know you'll be able to use strlen to
* determine the length, etc.
*
- * @return The raw data. Must be g_free'd when no longer needed.
+ * Returns: The raw data. Must be g_free'd when no longer needed.
*
* @see purple_base64_encode()
*/
@@ -313,10 +313,10 @@
* emails containing non-ASCII characters. Wikipedia has a pretty good
* explanation. Also see RFC 2045.
*
- * @param str The quoted printable ASCII string to convert to raw data.
- * @param ret_len The length of the returned data.
+ * @str: The quoted printable ASCII string to convert to raw data.
+ * @ret_len: The length of the returned data.
*
- * @return The readable string. Must be g_free'd when no longer needed.
+ * Returns: The readable string. Must be g_free'd when no longer needed.
*/
guchar *purple_quotedp_decode(const char *str, gsize *ret_len);
@@ -339,10 +339,10 @@
* question mark. The first piece is the character set, the second
* piece is the encoding, and the third piece is the encoded text.
*
- * @param str The ASCII string, possibly containing any number of
+ * @str: The ASCII string, possibly containing any number of
* encoded-word sections.
*
- * @return The string, with any encoded-word sections decoded and
+ * Returns: The string, with any encoded-word sections decoded and
* converted to UTF-8. Must be g_free'd when no longer
* needed.
*/
@@ -374,12 +374,12 @@
* abbreviation (as is the case on Unix). As with %z, conversion specifiers
* should not be used.
*
- * @param format The format string, in UTF-8
- * @param tm The time to format, or @c NULL to use the current local time
+ * @format: The format string, in UTF-8
+ * @tm: The time to format, or %NULL to use the current local time
*
- * @return The formatted time, in UTF-8.
+ * Returns: The formatted time, in UTF-8.
*
- * @note @a format is required to be in UTF-8. This differs from strftime(),
+ * Note: @a format is required to be in UTF-8. This differs from strftime(),
* where the format is provided in the locale charset.
*/
const char *purple_utf8_strftime(const char *format, const struct tm *tm);
@@ -387,8 +387,8 @@
/**
* Gets a string representation of the local timezone offset
*
- * @param tm The time to get the timezone for
- * @param iso TRUE to format the offset according to ISO-8601, FALSE to
+ * @tm: The time to get the timezone for
+ * @iso: TRUE to format the offset according to ISO-8601, FALSE to
* not substitute 'Z' for 0 offset, and to not separate
* hours and minutes with a colon.
*/
@@ -400,9 +400,9 @@
* The returned string is stored in a static buffer, so the result
* should be g_strdup()'d if it's going to be kept.
*
- * @param tm The time to format, or @c NULL to use the current local time
+ * @tm: The time to format, or %NULL to use the current local time
*
- * @return The date, formatted as per the user's settings. In the USA this
+ * Returns: The date, formatted as per the user's settings. In the USA this
* is something like "02/18/13"
*/
const char *purple_date_format_short(const struct tm *tm);
@@ -413,9 +413,9 @@
* The returned string is stored in a static buffer, so the result
* should be g_strdup()'d if it's going to be kept.
*
- * @param tm The time to format, or @c NULL to use the current local time
+ * @tm: The time to format, or %NULL to use the current local time
*
- * @return The timestamp, formatted as per the user's settings. In the USA
+ * Returns: The timestamp, formatted as per the user's settings. In the USA
* this is something like "02/18/13 15:26:44"
*/
const char *purple_date_format_long(const struct tm *tm);
@@ -426,9 +426,9 @@
* The returned string is stored in a static buffer, so the result
* should be g_strdup()'d if it's going to be kept.
*
- * @param tm The time to format, or @c NULL to use the current local time
+ * @tm: The time to format, or %NULL to use the current local time
*
- * @return The date and time, formatted as per the user's settings. In the
+ * Returns: The date and time, formatted as per the user's settings. In the
* USA this is something like "Mon Feb 18 15:26:44 2013"
*/
const char *purple_date_format_full(const struct tm *tm);
@@ -439,9 +439,9 @@
* The returned string is stored in a static buffer, so the result
* should be g_strdup()'d if it's going to be kept.
*
- * @param tm The time to format, or @c NULL to use the current local time
+ * @tm: The time to format, or %NULL to use the current local time
*
- * @return The time, formatted as per the user's settings. In the USA this
+ * Returns: The time, formatted as per the user's settings. In the USA this
* is something like "15:26:44"
*/
const char *purple_time_format(const struct tm *tm);
@@ -449,14 +449,14 @@
/**
* Builds a time_t from the supplied information.
*
- * @param year The year.
- * @param month The month.
- * @param day The day.
- * @param hour The hour.
- * @param min The minute.
- * @param sec The second.
+ * @year: The year.
+ * @month: The month.
+ * @day: The day.
+ * @hour: The hour.
+ * @min: The minute.
+ * @sec: The second.
*
- * @return A time_t.
+ * Returns: A time_t.
*/
time_t purple_time_build(int year, int month, int day, int hour,
int min, int sec);
@@ -469,21 +469,21 @@
* Parses a timestamp in jabber, ISO8601, or MM/DD/YYYY format and returns
* a time_t.
*
- * @param timestamp The timestamp
- * @param utc Assume UTC if no timezone specified
- * @param tm If not @c NULL, the caller can get a copy of the
+ * @timestamp: The timestamp
+ * @utc: Assume UTC if no timezone specified
+ * @tm: If not %NULL, the caller can get a copy of the
* struct tm used to calculate the time_t return value.
- * @param tz_off If not @c NULL, the caller can get a copy of the
+ * @tz_off: If not %NULL, the caller can get a copy of the
* timezone offset (from UTC) used to calculate the time_t
* return value. Note: Zero is a valid offset. As such,
* the value of the macro @c PURPLE_NO_TZ_OFF indicates no
* offset was specified (which means that the local
* timezone was used in the calculation).
- * @param rest If not @c NULL, the caller can get a pointer to the
+ * @rest: If not %NULL, the caller can get a pointer to the
* part of @a timestamp left over after parsing is
* completed, if it's not the end of @a timestamp.
*
- * @return A time_t.
+ * Returns: A time_t.
*/
time_t purple_str_to_time(const char *timestamp, gboolean utc,
struct tm *tm, long *tz_off, const char **rest);
@@ -491,13 +491,13 @@
/**
* Formats a datetime according to a UTS-35 Date Format Pattern.
*
- * @param format The formatting string, according to UTS #35
+ * @format: The formatting string, according to UTS #35
* See http://unicode.org/reports/tr35/
* (NOTE: not all formats are supported)
- * @param len The length of the formatting string
- * @param tm The time to format, or @c NULL to use the current local time
+ * @len: The length of the formatting string
+ * @tm: The time to format, or %NULL to use the current local time
*
- * @return The time, formatted as per the user's settings.
+ * Returns: The time, formatted as per the user's settings.
*/
char *purple_uts35_to_str(const char *format, size_t len, struct tm *tm);
@@ -527,13 +527,13 @@
* in a GData hash table. The names of the attributes are lower-cased
* in the hash table, and the name of the tag is case insensitive.
*
- * @param needle The name of the tag
- * @param haystack The null-delimited string to search in
- * @param start A pointer to the start of the tag if found
- * @param end A pointer to the end of the tag if found
- * @param attributes The attributes, if the tag was found. This should
+ * @needle: The name of the tag
+ * @haystack: The null-delimited string to search in
+ * @start: A pointer to the start of the tag if found
+ * @end: A pointer to the end of the tag if found
+ * @attributes: The attributes, if the tag was found. This should
* be freed with g_datalist_clear().
- * @return TRUE if the tag was found
+ * Returns: TRUE if the tag was found
*/
gboolean purple_markup_find_tag(const char *needle, const char *haystack,
const char **start, const char **end,
@@ -545,22 +545,22 @@
* This is a scary function. See protocols/msn/msn.c and
* protocols/yahoo/yahoo_profile.c for example usage.
*
- * @param str The string to parse.
- * @param len The size of str.
- * @param user_info The destination PurpleNotifyUserInfo to which the new
+ * @str: The string to parse.
+ * @len: The size of str.
+ * @user_info: The destination PurpleNotifyUserInfo to which the new
* field info should be added.
- * @param start_token The beginning token.
- * @param skip The number of characters to skip after the
+ * @start_token: The beginning token.
+ * @skip: The number of characters to skip after the
* start token.
- * @param end_token The ending token.
- * @param check_value The value that the last character must meet.
- * @param no_value_token The token indicating no value is given.
- * @param display_name The short descriptive name to display for this token.
- * @param is_link TRUE if this should be a link, or FALSE otherwise.
- * @param link_prefix The prefix for the link.
- * @param format_cb A callback to format the value before adding it.
+ * @end_token: The ending token.
+ * @check_value: The value that the last character must meet.
+ * @no_value_token: The token indicating no value is given.
+ * @display_name: The short descriptive name to display for this token.
+ * @is_link: TRUE if this should be a link, or FALSE otherwise.
+ * @link_prefix: The prefix for the link.
+ * @format_cb: A callback to format the value before adding it.
*
- * @return TRUE if successful, or FALSE otherwise.
+ * Returns: TRUE if successful, or FALSE otherwise.
*/
gboolean purple_markup_extract_info_field(const char *str, int len, PurpleNotifyUserInfo *user_info,
const char *start_token, int skip,
@@ -573,9 +573,9 @@
/**
* Converts HTML markup to XHTML.
*
- * @param html The HTML markup.
- * @param dest_xhtml The destination XHTML output.
- * @param dest_plain The destination plain-text output.
+ * @html: The HTML markup.
+ * @dest_xhtml: The destination XHTML output.
+ * @dest_plain: The destination plain-text output.
*/
void purple_markup_html_to_xhtml(const char *html, char **dest_xhtml,
char **dest_plain);
@@ -583,9 +583,9 @@
/**
* Strips HTML tags from a string.
*
- * @param str The string to strip HTML from.
+ * @str: The string to strip HTML from.
*
- * @return The new string without HTML. You must g_free this string
+ * Returns: The new string without HTML. You must g_free this string
* when finished with it.
*/
char *purple_markup_strip_html(const char *str);
@@ -593,9 +593,9 @@
/**
* Adds the necessary HTML code to turn URIs into HTML links in a string.
*
- * @param str The string to linkify.
+ * @str: The string to linkify.
*
- * @return The new string with all URIs surrounded in standard
+ * Returns: The new string with all URIs surrounded in standard
* HTML <a href="whatever"></a> tags. You must g_free this
* string when finished with it.
*/
@@ -611,9 +611,9 @@
*
* purple_unescape_html() is similar, but also converts "<br>" into "\n".
*
- * @param text The string in which to unescape any HTML entities
+ * @text: The string in which to unescape any HTML entities
*
- * @return The text with HTML entities literalized. You must g_free
+ * Returns: The text with HTML entities literalized. You must g_free
* this string when finished with it.
*
* @see purple_unescape_html()
@@ -624,9 +624,9 @@
* Unescapes HTML entities to their literal characters and converts
* "<br>" to "\n". See purple_unescape_text() for more details.
*
- * @param html The string in which to unescape any HTML entities
+ * @html: The string in which to unescape any HTML entities
*
- * @return The text with HTML entities literalized. You must g_free
+ * Returns: The text with HTML entities literalized. You must g_free
* this string when finished with it.
*
* @see purple_unescape_text()
@@ -646,13 +646,13 @@
* when used with other UI's. libpurple users are encouraged to report and
* work out any problems encountered.
*
- * @param str The input NUL terminated, HTML, UTF-8 (or ASCII) string.
- * @param x The character offset into an unformatted version of str to
+ * @str: The input NUL terminated, HTML, UTF-8 (or ASCII) string.
+ * @x: The character offset into an unformatted version of str to
* begin at.
- * @param y The character offset (into an unformatted vesion of str) of
+ * @y: The character offset (into an unformatted vesion of str) of
* one past the last character to include in the slice.
*
- * @return The HTML slice of string, with all formatting retained.
+ * Returns: The HTML slice of string, with all formatting retained.
*/
char *purple_markup_slice(const char *str, guint x, guint y);
@@ -662,8 +662,8 @@
* a '>' sometime after that. If there is no '>' and the string is
* not NUL terminated, this function can be expected to segfault.
*
- * @param tag The string starting a HTML tag.
- * @return A string containing the name of the tag.
+ * @tag: The string starting a HTML tag.
+ * Returns: A string containing the name of the tag.
*/
char *purple_markup_get_tag_name(const char *tag);
@@ -672,16 +672,16 @@
* entity pointed to by @a text. For example, purple_markup_unescape_entity("&")
* will return "&". The @a text variable is expected to point to an '&',
* the first character of the entity. If given an unrecognized entity, the function
- * returns @c NULL.
+ * returns %NULL.
*
* Note that this function, unlike purple_unescape_html(), does not search
* the string for the entity, does not replace the entity, and does not
* return a newly allocated string.
*
- * @param text A string containing an HTML entity.
- * @param length If not @c NULL, the string length of the entity is stored in this location.
+ * @text: A string containing an HTML entity.
+ * @length: If not %NULL, the string length of the entity is stored in this location.
*
- * @return A constant string containing the character representation of the given entity.
+ * Returns: A constant string containing the character representation of the given entity.
*/
const char * purple_markup_unescape_entity(const char *text, int *length);
@@ -694,21 +694,21 @@
* "color") would return "#dc4d1b".
*
* On error or if the requested property was not found, the function returns
- * @c NULL.
+ * %NULL.
*
- * @param style A string containing the inline CSS text.
- * @param opt The requested CSS property.
+ * @style: A string containing the inline CSS text.
+ * @opt: The requested CSS property.
*
- * @return The value of the requested CSS property.
+ * Returns: The value of the requested CSS property.
*/
char * purple_markup_get_css_property(const gchar *style, const gchar *opt);
/**
* Check if the given HTML contains RTL text.
*
- * @param html The HTML text.
+ * @html: The HTML text.
*
- * @return TRUE if the text contains RTL text, FALSE otherwise.
+ * Returns: TRUE if the text contains RTL text, FALSE otherwise.
*/
gboolean purple_markup_is_rtl(const char *html);
@@ -723,7 +723,7 @@
/**
* Returns the user's home directory.
*
- * @return The user's home directory.
+ * Returns: The user's home directory.
*
* @see purple_user_dir()
*/
@@ -733,7 +733,7 @@
* Returns the purple settings directory in the user's home directory.
* This is usually ~/.purple
*
- * @return The purple settings directory.
+ * Returns: The purple settings directory.
*
* @see purple_home_dir()
*/
@@ -741,7 +741,7 @@
/**
* Define a custom purple settings directory, overriding the default (user's home directory/.purple)
- * @param dir The custom settings directory
+ * @dir: The custom settings directory
*/
void purple_util_set_user_dir(const char *dir);
@@ -749,11 +749,11 @@
* Builds a complete path from the root, making any directories along
* the path which do not already exist.
*
- * @param path The path you wish to create. Note that it must start
+ * @path: The path you wish to create. Note that it must start
* from the root or this function will fail.
- * @param mode Unix-style permissions for this directory.
+ * @mode: Unix-style permissions for this directory.
*
- * @return 0 for success, nonzero on any error.
+ * Returns: 0 for success, nonzero on any error.
*/
int purple_build_dir(const char *path, int mode);
@@ -765,12 +765,12 @@
* obtained using purple_xmlnode_to_formatted_str. However, this function
* should work fine for saving binary files as well.
*
- * @param filename The basename of the file to write in the purple_user_dir.
- * @param data A null-terminated string of data to write.
- * @param size The size of the data to save. If data is
+ * @filename: The basename of the file to write in the purple_user_dir.
+ * @data: A null-terminated string of data to write.
+ * @size: The size of the data to save. If data is
* null-terminated you can pass in -1.
*
- * @return TRUE if the file was written successfully. FALSE otherwise.
+ * Returns: TRUE if the file was written successfully. FALSE otherwise.
*/
gboolean purple_util_write_data_to_file(const char *filename, const char *data,
gssize size);
@@ -780,12 +780,12 @@
*
* This exists for Glib backwards compatibility reasons.
*
- * @param filename_full Filename to write to
- * @param data A null-terminated string of data to write.
- * @param size The size of the data to save. If data is
+ * @filename_full: Filename to write to
+ * @data: A null-terminated string of data to write.
+ * @size: The size of the data to save. If data is
* null-terminated you can pass in -1.
*
- * @return TRUE if the file was written successfully. FALSE otherwise.
+ * Returns: TRUE if the file was written successfully. FALSE otherwise.
*
* @todo Remove this function (use g_file_set_contents instead) when 3.0.0
* rolls around.
@@ -800,13 +800,13 @@
* PurpleXmlNode tree structure. This is intended to be used to read
* Purple's configuration xml files (prefs.xml, pounces.xml, etc.)
*
- * @param filename The basename of the file to open in the purple_user_dir.
- * @param description A very short description of the contents of this
+ * @filename: The basename of the file to open in the purple_user_dir.
+ * @description: A very short description of the contents of this
* file. This is used in error messages shown to the
* user when the file can not be opened. For example,
* "preferences," or "buddy pounces."
*
- * @return An PurpleXmlNode tree of the contents of the given file. Or NULL, if
+ * Returns: An PurpleXmlNode tree of the contents of the given file. Or NULL, if
* the file does not exist or there was an error reading the file.
*/
PurpleXmlNode *purple_util_read_xml_from_file(const char *filename,
@@ -823,26 +823,26 @@
* done, as well as freeing the space pointed to by @a path with
* g_free().
*
- * @param path The returned path to the temp file.
- * @param binary Text or binary, for platforms where it matters.
+ * @path: The returned path to the temp file.
+ * @binary: Text or binary, for platforms where it matters.
*
- * @return A file pointer to the temporary file, or @c NULL on failure.
+ * Returns: A file pointer to the temporary file, or %NULL on failure.
*/
FILE *purple_mkstemp(char **path, gboolean binary);
/**
* Returns an extension corresponding to the image data's file type.
*
- * @param data A pointer to the image data
- * @param len The length of the image data
+ * @data: A pointer to the image data
+ * @len: The length of the image data
*
- * @return The appropriate extension, or "icon" if unknown.
+ * Returns: The appropriate extension, or "icon" if unknown.
*/
const char *
purple_util_get_image_extension(gconstpointer data, size_t len);
/**
- * @return A hex encoded version of the SHA-1 hash of the data passed
+ * Returns: A hex encoded version of the SHA-1 hash of the data passed
* in with the correct file extention appended. The file
* extension is determined by calling
* purple_util_get_image_extension(). This return value must
@@ -861,48 +861,48 @@
/**
* Checks if the given program name is valid and executable.
*
- * @param program The file name of the application.
+ * @program: The file name of the application.
*
- * @return TRUE if the program is runable.
+ * Returns: TRUE if the program is runable.
*/
gboolean purple_program_is_valid(const char *program);
/**
* Check if running GNOME.
*
- * @return TRUE if running GNOME, FALSE otherwise.
+ * Returns: TRUE if running GNOME, FALSE otherwise.
*/
gboolean purple_running_gnome(void);
/**
* Check if running KDE.
*
- * @return TRUE if running KDE, FALSE otherwise.
+ * Returns: TRUE if running KDE, FALSE otherwise.
*/
gboolean purple_running_kde(void);
/**
* Check if running OS X.
*
- * @return TRUE if running OS X, FALSE otherwise.
+ * Returns: TRUE if running OS X, FALSE otherwise.
*/
gboolean purple_running_osx(void);
/**
* Returns the IP address from a socket file descriptor.
*
- * @param fd The socket file descriptor.
+ * @fd: The socket file descriptor.
*
- * @return The IP address, or @c NULL on error.
+ * Returns: The IP address, or %NULL on error.
*/
char *purple_fd_get_ip(int fd);
/**
* Returns the address family of a socket.
*
- * @param fd The socket file descriptor.
+ * @fd: The socket file descriptor.
*
- * @return The address family of the socket (AF_INET, AF_INET6, etc) or -1
+ * Returns: The address family of the socket (AF_INET, AF_INET6, etc) or -1
* on error.
*/
int purple_socket_get_family(int fd);
@@ -913,8 +913,8 @@
* This is the case for IPv4 sockets and, on some systems, IPv6 sockets
* (due to the IPv4-mapped address functionality).
*
- * @param fd The socket file descriptor
- * @return TRUE if a socket can speak IPv4.
+ * @fd: The socket file descriptor
+ * Returns: TRUE if a socket can speak IPv4.
*/
gboolean purple_socket_speaks_ipv4(int fd);
@@ -930,12 +930,12 @@
* Tests two strings for equality.
*
* Unlike strcmp(), this function will not crash if one or both of the
- * strings are @c NULL.
+ * strings are %NULL.
*
- * @param left A string
- * @param right A string to compare with left
+ * @left: A string
+ * @right: A string to compare with left
*
- * @return @c TRUE if the strings are the same, else @c FALSE.
+ * Returns: %TRUE if the strings are the same, else %FALSE.
*/
gboolean purple_strequal(const gchar *left, const gchar *right);
@@ -947,14 +947,14 @@
* g_strdup() it. Also, calling normalize() twice in the same line
* will lead to problems.
*
- * @param account The account the string belongs to, or NULL if you do
+ * @account: The account the string belongs to, or NULL if you do
* not know the account. If you use NULL, the string
* will still be normalized, but if the PRPL uses a
* custom normalization function then the string may
* not be normalized correctly.
- * @param str The string to normalize.
+ * @str: The string to normalize.
*
- * @return A pointer to the normalized version stored in a static buffer.
+ * Returns: A pointer to the normalized version stored in a static buffer.
*/
const char *purple_normalize(const PurpleAccount *account, const char *str);
@@ -965,20 +965,20 @@
* function "normalize." It returns a lowercase and UTF-8
* normalized version of the string.
*
- * @param account The account the string belongs to.
- * @param str The string to normalize.
+ * @account: The account the string belongs to.
+ * @str: The string to normalize.
*
- * @return A pointer to the normalized version stored in a static buffer.
+ * Returns: A pointer to the normalized version stored in a static buffer.
*/
const char *purple_normalize_nocase(const PurpleAccount *account, const char *str);
/**
* Checks, if a string is valid.
*
- * @param prpl The protocol plugin the string belongs to.
- * @param str The string to validate.
+ * @prpl: The protocol plugin the string belongs to.
+ * @str: The string to validate.
*
- * @return TRUE, if string is valid, otherwise FALSE.
+ * Returns: TRUE, if string is valid, otherwise FALSE.
*/
gboolean purple_validate(const PurplePlugin *prpl, const char *str);
@@ -986,10 +986,10 @@
* Compares two strings to see if the first contains the second as
* a proper prefix.
*
- * @param s The string to check.
- * @param p The prefix in question.
+ * @s: The string to check.
+ * @p: The prefix in question.
*
- * @return TRUE if p is a prefix of s, otherwise FALSE.
+ * Returns: TRUE if p is a prefix of s, otherwise FALSE.
*/
gboolean purple_str_has_prefix(const char *s, const char *p);
@@ -997,10 +997,10 @@
* Compares two strings to see if the second is a proper suffix
* of the first.
*
- * @param s The string to check.
- * @param x The suffix in question.
+ * @s: The string to check.
+ * @x: The suffix in question.
*
- * @return TRUE if x is a a suffix of s, otherwise FALSE.
+ * Returns: TRUE if x is a a suffix of s, otherwise FALSE.
*/
gboolean purple_str_has_suffix(const char *s, const char *x);
@@ -1008,18 +1008,18 @@
* Duplicates a string and replaces all newline characters from the
* source string with HTML linebreaks.
*
- * @param src The source string.
+ * @src: The source string.
*
- * @return The new string. Must be g_free'd by the caller.
+ * Returns: The new string. Must be g_free'd by the caller.
*/
gchar *purple_strdup_withhtml(const gchar *src);
/**
* Ensures that all linefeeds have a matching carriage return.
*
- * @param str The source string.
+ * @str: The source string.
*
- * @return The string with carriage returns.
+ * Returns: The string with carriage returns.
*/
char *purple_str_add_cr(const char *str);
@@ -1031,8 +1031,8 @@
* Example usage:
* purple_str_strip_char(my_dumb_string, '\n');
*
- * @param str The string to strip characters from.
- * @param thechar The character to strip from the given string.
+ * @str: The string to strip characters from.
+ * @thechar: The character to strip from the given string.
*/
void purple_str_strip_char(char *str, char thechar);
@@ -1041,9 +1041,9 @@
* with another. This happens inline (the original string IS
* modified).
*
- * @param string The string from which to replace stuff.
- * @param delimiter The character you want replaced.
- * @param replacement The character you want inserted in place
+ * @string: The string from which to replace stuff.
+ * @delimiter: The character you want replaced.
+ * @replacement: The character you want inserted in place
* of the delimiting character.
*/
void purple_util_chrreplace(char *string, char delimiter,
@@ -1053,12 +1053,12 @@
* Given a string, this replaces one substring with another
* and returns a newly allocated string.
*
- * @param string The string from which to replace stuff.
- * @param delimiter The substring you want replaced.
- * @param replacement The substring you want inserted in place
+ * @string: The string from which to replace stuff.
+ * @delimiter: The substring you want replaced.
+ * @replacement: The substring you want inserted in place
* of the delimiting substring.
*
- * @return A new string, after performing the substitution.
+ * Returns: A new string, after performing the substitution.
* free this with g_free().
*/
gchar *purple_strreplace(const char *string, const char *delimiter,
@@ -1070,9 +1070,9 @@
* the corresponding numerical character reference, and returns a newly
* allocated string.
*
- * @param in The string which might contain utf-8 substrings
+ * @in: The string which might contain utf-8 substrings
*
- * @return A new string, with utf-8 replaced with numerical character
+ * Returns: A new string, with utf-8 replaced with numerical character
* references, free this with g_free()
*/
char *purple_utf8_ncr_encode(const char *in);
@@ -1083,9 +1083,9 @@
* in that string with the corresponding actual utf-8 substrings,
* and returns a newly allocated string.
*
- * @param in The string which might contain numerical character references.
+ * @in: The string which might contain numerical character references.
*
- * @return A new string, with numerical character references
+ * Returns: A new string, with numerical character references
* replaced with actual utf-8, free this with g_free().
*/
char *purple_utf8_ncr_decode(const char *in);
@@ -1095,12 +1095,12 @@
* Given a string, this replaces one substring with another
* ignoring case and returns a newly allocated string.
*
- * @param string The string from which to replace stuff.
- * @param delimiter The substring you want replaced.
- * @param replacement The substring you want inserted in place
+ * @string: The string from which to replace stuff.
+ * @delimiter: The substring you want replaced.
+ * @replacement: The substring you want inserted in place
* of the delimiting substring.
*
- * @return A new string, after performing the substitution.
+ * Returns: A new string, after performing the substitution.
* free this with g_free().
*/
gchar *purple_strcasereplace(const char *string, const char *delimiter,
@@ -1110,10 +1110,10 @@
* This is like strstr, except that it ignores ASCII case in
* searching for the substring.
*
- * @param haystack The string to search in.
- * @param needle The substring to find.
+ * @haystack: The string to search in.
+ * @needle: The substring to find.
*
- * @return the location of the substring if found, or NULL if not
+ * Returns: the location of the substring if found, or NULL if not
*/
const char *purple_strcasestr(const char *haystack, const char *needle);
@@ -1121,18 +1121,18 @@
* Returns a string representing a filesize in the appropriate
* units (MB, KB, GB, etc.)
*
- * @param size The size
+ * @size: The size
*
- * @return The string in units form. This must be freed.
+ * Returns: The string in units form. This must be freed.
*/
char *purple_str_size_to_units(goffset size);
/**
* Converts seconds into a human-readable form.
*
- * @param sec The seconds.
+ * @sec: The seconds.
*
- * @return A human-readable form, containing days, hours, minutes, and
+ * Returns: A human-readable form, containing days, hours, minutes, and
* seconds.
*/
char *purple_str_seconds_to_string(guint sec);
@@ -1144,19 +1144,19 @@
* changed into two backslashes (\\\\). The returned, newly allocated
* string can be outputted to the console, and must be g_free()d.
*
- * @param binary A string of random data, possibly with embedded NULs
+ * @binary: A string of random data, possibly with embedded NULs
* and such.
- * @param len The length in bytes of the input string. Must not be 0.
+ * @len: The length in bytes of the input string. Must not be 0.
*
- * @return A newly allocated ASCIIZ string.
+ * Returns: A newly allocated ASCIIZ string.
*/
char *purple_str_binary_to_ascii(const unsigned char *binary, guint len);
/**
* Calculates UTF-16 string size (in bytes).
*
- * @param str String to check.
- * @return Number of bytes (including NUL character) that string occupies.
+ * @str: String to check.
+ * Returns: Number of bytes (including NUL character) that string occupies.
*/
size_t purple_utf16_size(const gunichar2 *str);
@@ -1165,7 +1165,7 @@
*
* It should be used to free sensitive data, like passwords.
*
- * @param str A NUL-terminated string to free, or a NULL-pointer.
+ * @str: A NUL-terminated string to free, or a NULL-pointer.
*/
void purple_str_wipe(gchar *str);
@@ -1174,7 +1174,7 @@
*
* It should be used to free sensitive data, like passwords.
*
- * @param str A NUL-terminated string to free, or a NULL-pointer.
+ * @str: A NUL-terminated string to free, or a NULL-pointer.
*/
void purple_utf16_wipe(gunichar2 *str);
@@ -1193,9 +1193,9 @@
*
* This will change hex codes and such to their ascii equivalents.
*
- * @param str The string to translate.
+ * @str: The string to translate.
*
- * @return The resulting string.
+ * Returns: The resulting string.
*/
const char *purple_url_decode(const char *str);
@@ -1204,18 +1204,18 @@
*
* This will change non-alphanumeric characters to hex codes.
*
- * @param str The string to translate.
+ * @str: The string to translate.
*
- * @return The resulting string.
+ * Returns: The resulting string.
*/
const char *purple_url_encode(const char *str);
/**
* Checks if the given email address is syntactically valid.
*
- * @param address The email address to validate.
+ * @address: The email address to validate.
*
- * @return True if the email address is syntactically correct.
+ * Returns: True if the email address is syntactically correct.
*/
gboolean purple_email_is_valid(const char *address);
@@ -1226,27 +1226,27 @@
* purple_ipv4_address_is_valid(), or for an IPv6 address use
* purple_ipv6_address_is_valid().
*
- * @param ip The IP address to validate.
+ * @ip: The IP address to validate.
*
- * @return True if the IP address is syntactically correct.
+ * Returns: True if the IP address is syntactically correct.
*/
gboolean purple_ip_address_is_valid(const char *ip);
/**
* Checks if the given IP address is a syntactically valid IPv4 address.
*
- * @param ip The IP address to validate.
+ * @ip: The IP address to validate.
*
- * @return True if the IP address is syntactically correct.
+ * Returns: True if the IP address is syntactically correct.
*/
gboolean purple_ipv4_address_is_valid(const char *ip);
/**
* Checks if the given IP address is a syntactically valid IPv6 address.
*
- * @param ip The IP address to validate.
+ * @ip: The IP address to validate.
*
- * @return True if the IP address is syntactically correct.
+ * Returns: True if the IP address is syntactically correct.
*/
gboolean purple_ipv6_address_is_valid(const char *ip);
@@ -1254,9 +1254,9 @@
* This function extracts a list of URIs from the a "text/uri-list"
* string. It was "borrowed" from gnome_uri_list_extract_uris
*
- * @param uri_list An uri-list in the standard format.
+ * @uri_list: An uri-list in the standard format.
*
- * @return A GList containing strings allocated with g_malloc
+ * Returns: A GList containing strings allocated with g_malloc
* that have been splitted from uri-list.
*/
GList *purple_uri_list_extract_uris(const gchar *uri_list);
@@ -1266,9 +1266,9 @@
* "text/uri-list" string. It was "borrowed" from
* gnome_uri_list_extract_filenames
*
- * @param uri_list A uri-list in the standard format.
+ * @uri_list: A uri-list in the standard format.
*
- * @return A GList containing strings allocated with g_malloc that
+ * Returns: A GList containing strings allocated with g_malloc that
* contain the filenames in the uri-list. Note that unlike
* purple_uri_list_extract_uris() function, this will discard
* any non-file uri from the result value.
@@ -1287,9 +1287,9 @@
*
* This function checks the locale and tries sane defaults.
*
- * @param str The source string.
+ * @str: The source string.
*
- * @return The UTF-8 string, or @c NULL if it could not be converted.
+ * Returns: The UTF-8 string, or %NULL if it could not be converted.
*/
gchar *purple_utf8_try_convert(const char *str);
@@ -1298,9 +1298,9 @@
* invalid characters with a filler character (currently hardcoded to
* '?').
*
- * @param str The source string.
+ * @str: The source string.
*
- * @return A valid UTF-8 string.
+ * Returns: A valid UTF-8 string.
*/
gchar *purple_utf8_salvage(const char *str);
@@ -1311,9 +1311,9 @@
*
* The returned string must be freed by the caller.
*
- * @param str A valid UTF-8 string.
+ * @str: A valid UTF-8 string.
*
- * @return A newly allocated UTF-8 string without the unprintable characters.
+ * Returns: A newly allocated UTF-8 string without the unprintable characters.
*/
gchar *purple_utf8_strip_unprintables(const gchar *str);
@@ -1322,9 +1322,9 @@
* then converts the result to UTF-8. This function is analogous to
* g_strerror().
*
- * @param errnum The error code.
+ * @errnum: The error code.
*
- * @return The UTF-8 error message.
+ * Returns: The UTF-8 error message.
*/
const gchar *purple_gai_strerror(gint errnum);
@@ -1334,10 +1334,10 @@
* it calls g_utf8_casefold() on each string, which allocates new
* strings.
*
- * @param a The first string.
- * @param b The second string.
+ * @a: The first string.
+ * @b: The second string.
*
- * @return -1 if @a a is less than @a b.
+ * Returns: -1 if @a a is less than @a b.
* 0 if @a a is equal to @a b.
* 1 if @a a is greater than @a b.
*/
@@ -1348,10 +1348,10 @@
* must be contained in the haystack string and not be immediately
* preceded or immediately followed by another alpha-numeric character.
*
- * @param haystack The string to search in.
- * @param needle The substring to find.
+ * @haystack: The string to search in.
+ * @needle: The substring to find.
*
- * @return TRUE if haystack has the word, otherwise FALSE
+ * Returns: TRUE if haystack has the word, otherwise FALSE
*/
gboolean purple_utf8_has_word(const char *haystack, const char *needle);
@@ -1360,18 +1360,18 @@
* tries to convert the UTF-8 message to user's locale. If this
* is not possible, the original UTF-8 text will be printed.
*
- * @param filestream The file stream (e.g. STDOUT or STDERR)
- * @param message The message to print.
+ * @filestream: The file stream (e.g. STDOUT or STDERR)
+ * @message: The message to print.
*/
void purple_print_utf8_to_console(FILE *filestream, char *message);
/**
* Checks for messages starting (post-HTML) with "/me ", including the space.
*
- * @param message The message to check
- * @param len The message length, or -1
+ * @message: The message to check
+ * @len: The message length, or -1
*
- * @return TRUE if it starts with "/me ", and it has been removed, otherwise
+ * Returns: TRUE if it starts with "/me ", and it has been removed, otherwise
* FALSE
*/
gboolean purple_message_meify(char *message, gssize len);
@@ -1380,9 +1380,9 @@
* Removes the underscore characters from a string used identify the mnemonic
* character.
*
- * @param in The string to strip
+ * @in: The string to strip
*
- * @return The stripped string
+ * Returns: The stripped string
*/
char *purple_text_strip_mnemonic(const char *in);
@@ -1393,9 +1393,9 @@
*
* Blame SimGuy.
*
- * @param x The number to add 8 to.
+ * @x: The number to add 8 to.
*
- * @return x + 8
+ * Returns: x + 8
*/
#define purple_add_eight(x) ((x)+8)
@@ -1404,27 +1404,27 @@
*
* This will change hex codes and such to their ascii equivalents.
*
- * @param str The string to translate.
+ * @str: The string to translate.
*
- * @return The resulting string.
+ * Returns: The resulting string.
*/
const char *purple_unescape_filename(const char *str);
/**
* Escapes filesystem-unfriendly characters from a filename
*
- * @param str The string to translate.
+ * @str: The string to translate.
*
- * @return The resulting string.
+ * Returns: The resulting string.
*/
const char *purple_escape_filename(const char *str);
/**
* Escapes javascript-unfriendly substrings from a string.
*
- * @param str The string to escape.
+ * @str: The string to escape.
*
- * @return The javascript-safe string (must be g_free'd after use).
+ * Returns: The javascript-safe string (must be g_free'd after use).
*/
gchar * purple_escape_js(const gchar *str);
@@ -1439,14 +1439,14 @@
* Gets the host name of the machine. If it not possible to determine the
* host name, "localhost" is returned
*
- * @constreturn The hostname
+ * Returns: (TODO const): The hostname
*/
const gchar *purple_get_host_name(void);
/**
* Returns a type 4 (random) UUID
*
- * @return A UUID, caller is responsible for freeing it
+ * Returns: A UUID, caller is responsible for freeing it
*/
gchar *purple_uuid_random(void);
@@ -1455,32 +1455,32 @@
*
* Function designed to be used as a GDestroyNotify callback.
*
- * @param data A pointer to variable, which should be set to NULL.
+ * @data: A pointer to variable, which should be set to NULL.
*/
void purple_callback_set_zero(gpointer data);
/**
* Creates a new GValue of the specified type.
*
- * @param type The type of data to be held by the GValue
+ * @type: The type of data to be held by the GValue
*
- * @return The created GValue
+ * Returns: The created GValue
*/
GValue *purple_value_new(GType type);
/**
* Duplicates a GValue.
*
- * @param value The GValue to duplicate
+ * @value: The GValue to duplicate
*
- * @return The duplicated GValue
+ * Returns: The duplicated GValue
*/
GValue *purple_value_dup(GValue *value);
/**
* Frees a GValue.
*
- * @param value The GValue to free.
+ * @value: The GValue to free.
*/
void purple_value_free(GValue *value);
@@ -1489,14 +1489,14 @@
*
* See RFC 2617 for more information.
*
- * @param algorithm The hash algorithm to use
- * @param username The username provided by the user
- * @param realm The authentication realm provided by the server
- * @param password The password provided by the user
- * @param nonce The nonce provided by the server
- * @param client_nonce The nonce provided by the client
+ * @algorithm: The hash algorithm to use
+ * @username: The username provided by the user
+ * @realm: The authentication realm provided by the server
+ * @password: The password provided by the user
+ * @nonce: The nonce provided by the server
+ * @client_nonce: The nonce provided by the client
*
- * @return The session key, or @c NULL if an error occurred.
+ * Returns: The session key, or %NULL if an error occurred.
*/
gchar *purple_http_digest_calculate_session_key(
const gchar *algorithm, const gchar *username,
@@ -1507,17 +1507,17 @@
*
* See RFC 2617 for more information.
*
- * @param algorithm The hash algorithm to use
- * @param method The HTTP method in use
- * @param digest_uri The URI from the initial request
- * @param qop The "quality of protection"
- * @param entity The entity body
- * @param nonce The nonce provided by the server
- * @param nonce_count The nonce count
- * @param client_nonce The nonce provided by the client
- * @param session_key The session key from purple_cipher_http_digest_calculate_session_key()
+ * @algorithm: The hash algorithm to use
+ * @method: The HTTP method in use
+ * @digest_uri: The URI from the initial request
+ * @qop: The "quality of protection"
+ * @entity: The entity body
+ * @nonce: The nonce provided by the server
+ * @nonce_count: The nonce count
+ * @client_nonce: The nonce provided by the client
+ * @session_key: The session key from purple_cipher_http_digest_calculate_session_key()
*
- * @return The hashed response, or @c NULL if an error occurred.
+ * Returns: The hashed response, or %NULL if an error occurred.
*/
gchar *purple_http_digest_calculate_response(
const gchar *algorithm, const gchar *method,