From 66445dd9eaf88192117b4fae33ee77896ef82a0c Mon Sep 17 00:00:00 2001 From: Charles Day Date: Fri, 4 Apr 2008 15:43:17 +0000 Subject: [PATCH] Improve documentation of GLib helper functions for doxygen. In particular, move these functions out of the GConf section and fix the broken documentation of gnc_utf8_validate(), which doesn't appear to have been written for doxygen. Requesting backport because a significant percentage of lines have changed. BP git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@17064 57a11ea4-9604-0410-9ed3-97b8803252fd --- src/core-utils/gnc-glib-utils.h | 71 +++++++++++++++++++++------------ 1 file changed, 45 insertions(+), 26 deletions(-) diff --git a/src/core-utils/gnc-glib-utils.h b/src/core-utils/gnc-glib-utils.h index f8fc5f20c3..ec1ad30775 100644 --- a/src/core-utils/gnc-glib-utils.h +++ b/src/core-utils/gnc-glib-utils.h @@ -23,7 +23,7 @@ /** @addtogroup GLib @{ */ -/** @addtogroup GConf GConf Utilities +/** @addtogroup Helpers GLib Helpers The API in this file is designed to provide support functions that wrap the base glib functions and make them easier to use. @@ -39,11 +39,11 @@ #include -/** @name glib Miscellaneous Functions +/** @name Character Sets @{ */ -/** Collate two utf8 strings. This function performs basic argument +/** Collate two UTF-8 strings. This function performs basic argument * checking before calling g_utf8_collate. * * @param str1 The first string. @@ -56,33 +56,32 @@ int safe_utf8_collate (const char *str1, const char *str2); /** - * gnc_utf8_validate (copied from g_utf8_validate): - * @str: a pointer to character data - * @max_len: max bytes to validate, or -1 to go until nul - * @end: return location for end of valid data - * - * Validates UTF-8 encoded text. @str is the text to validate; - * if @str is nul-terminated, then @max_len can be -1, otherwise - * @max_len should be the number of bytes to validate. - * If @end is non-%NULL, then the end of the valid range - * will be stored there (i.e. the address of the first invalid byte - * if some bytes were invalid, or the end of the text being validated - * otherwise). + * @brief Validates UTF-8 encoded text for use in GnuCash. + * Validates the strict subset of UTF-8 that is valid XML text, as detailed in + * http://www.w3.org/TR/REC-xml/#NT-Char linked from bug #346535. * - * This function looks validates the strict subset of UTF-8 that is - * valid XML text, as detailed in - * http://www.w3.org/TR/REC-xml/#NT-Char linked from bug #346535 + * (copied from g_utf8_validate): + * Validates UTF-8 encoded text, where @a str is the text to validate; if + * @a str is nul-terminated, then @a max_len can be -1, otherwise @a max_len + * should be the number of bytes to validate. If @a end is non-%NULL, then the + * end of the valid range will be stored there (i.e. the start of the first + * invalid character if some bytes were invalid, or the end of the text being + * validated otherwise). * - * Returns %TRUE if all of @str was valid. Many GLib and GTK+ - * routines require valid UTF-8 as input; + * Returns %TRUE if all of @a str was valid. Many GLib and GTK+ + * routines @e require valid UTF-8 as input; * so data read from a file or the network should be checked * with g_utf8_validate() before doing anything else with it. * - * Return value: %TRUE if the text was valid UTF-8 + * @param str a pointer to character data + * @param max_len max bytes to validate, or -1 to go until NUL + * @param end return location for end of valid data + * + * @return %TRUE if the text was valid UTF-8. **/ gboolean gnc_utf8_validate(const gchar *str, gssize max_len, const gchar **end); -/** Strip any non-utf8 characters from a string. This function +/** Strip any non-UTF-8 characters from a string. This function * rewrites the string "in place" instead of allocating and returning * a new string. This allows it to operate on strings that are * defined as character arrays in a larger data structure. Note that @@ -94,20 +93,22 @@ gboolean gnc_utf8_validate(const gchar *str, gssize max_len, const gchar **end); void gnc_utf8_strip_invalid (gchar *str); /** Returns a newly allocated copy of the given string but with any - * non-utf8 character stripped from it. + * non-UTF-8 character stripped from it. * * Note that it also removes some subset of invalid XML characters, * too. See http://www.w3.org/TR/REC-xml/#NT-Char linked from bug * #346535 * * @param str A pointer to the string to be copied and stripped of - * non-utf8 characters. + * non-UTF-8 characters. * * @return A newly allocated string that has to be g_free'd by the * caller. */ gchar *gnc_utf8_strip_invalid_strdup (const gchar* str); -/** Converts a string from UTF-8 to the encoding used for strings +/** + * @brief Converts a string from UTF-8 to the current locale. + * Converts a string from UTF-8 to the encoding used for strings * in the current locale. * * This essentially is a wrapper for g_locale_from_utf8 that can @@ -120,7 +121,9 @@ gchar *gnc_utf8_strip_invalid_strdup (const gchar* str); * caller. If an error occurs, NULL is returned. */ gchar *gnc_locale_from_utf8(const gchar* str); -/** Converts a string to UTF-8 from the encoding used for strings +/** + * @brief Converts a string to UTF-8 from the current locale. + * Converts a string to UTF-8 from the encoding used for strings * in the current locale. * * This essentially is a wrapper for g_locale_to_utf8 that can @@ -133,6 +136,11 @@ gchar *gnc_locale_from_utf8(const gchar* str); * caller. If an error occurs, NULL is returned. */ gchar *gnc_locale_to_utf8(const gchar* str); +/** @} */ + +/** @name GList Manipulation + @{ +*/ typedef gpointer (*GncGMapFunc)(gpointer data, gpointer user_data); /** @@ -147,11 +155,22 @@ GList* gnc_g_list_map(GList* list, GncGMapFunc fn, gpointer user_data); **/ void gnc_g_list_cut(GList **list, GList *cut_point); +/** @} */ + +/** @name Message Logging + @{ +*/ void gnc_scm_log_warn(const gchar *msg); void gnc_scm_log_error(const gchar *msg); void gnc_scm_log_msg(const gchar *msg); void gnc_scm_log_debug(const gchar *msg); +/** @} */ + +/** @name glib Miscellaneous Functions + @{ +*/ + /** Kill a process. On UNIX send a SIGKILL, on Windows call TerminateProcess. * * @param pid The process ID. */