AUDIT: r17064 - gnucash/trunk/src/core-utils - Improve documentation of GLib helper functions for doxygen. In particular, move
Charles Day
cedayiv at cvs.gnucash.org
Fri Apr 4 11:43:18 EDT 2008
Author: cedayiv
Date: 2008-04-04 11:43:17 -0400 (Fri, 04 Apr 2008)
New Revision: 17064
Trac: http://svn.gnucash.org/trac/changeset/17064
Modified:
gnucash/trunk/src/core-utils/gnc-glib-utils.h
Log:
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
Modified: gnucash/trunk/src/core-utils/gnc-glib-utils.h
===================================================================
--- gnucash/trunk/src/core-utils/gnc-glib-utils.h 2008-04-02 18:10:35 UTC (rev 17063)
+++ gnucash/trunk/src/core-utils/gnc-glib-utils.h 2008-04-04 15:43:17 UTC (rev 17064)
@@ -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 @@
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 @@
* 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 @@
* 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 @@
**/
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. */
More information about the gnucash-changes
mailing list