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

@@ -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 <glib.h>
 
-/** @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 <emphasis>require</emphasis> 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. */