glib r7761 - in trunk: . docs/reference docs/reference/glib/tmpl glib

[matthiasc svn gnome org]

Author: matthiasc
Date: Sat Jan  3 04:15:17 2009
New Revision: 7761
URL: http://svn.gnome.org/viewvc/glib?rev=7761&view=rev

Log:
Move docs inline


Modified:
   trunk/ChangeLog
   trunk/docs/reference/ChangeLog
   trunk/docs/reference/glib/tmpl/string_utils.sgml
   trunk/glib/gstrfuncs.c

Modified: trunk/docs/reference/glib/tmpl/string_utils.sgml
==============================================================================
--- trunk/docs/reference/glib/tmpl/string_utils.sgml	(original)
+++ trunk/docs/reference/glib/tmpl/string_utils.sgml	Sat Jan  3 04:15:17 2009
@@ -42,13 +42,11 @@
 
 <!-- ##### FUNCTION g_strdup ##### -->
 <para>
-Duplicates a string.
-If @str is %NULL it returns %NULL.
-The returned string should be freed when no longer needed.
+
 </para>
 
- str: the string to duplicate.
- Returns: a newly-allocated copy of @str.
+ str: 
+ Returns: 
 
 
 <!-- ##### FUNCTION g_strndup ##### -->
@@ -153,65 +151,43 @@
 
 <!-- ##### FUNCTION g_strlcpy ##### -->
 <para>
-Portability wrapper that calls strlcpy() on systems which have it, and emulates
-strlcpy() otherwise. Copies @src to @dest; @dest is guaranteed to be
-nul-terminated; @src must be nul-terminated; @dest_size is the buffer size, not
-the number of chars to copy. Caveat: strlcpy() is supposedly more secure than
-strcpy() or strncpy(), but if you really want to avoid screwups, g_strdup() is
-an even better idea.
+
 </para>
 
- dest: destination buffer
- src: source buffer
- dest_size: length of @dest in bytes
- Returns: length of @src
+ dest:
+ src:
+ dest_size: 
+ Returns: 
 
 
 <!-- ##### FUNCTION g_strlcat ##### -->
 <para>
-Portability wrapper that calls strlcat() on systems which have it, and emulates it otherwise. 
-Appends nul-terminated @src string to @dest, guaranteeing
-nul-termination for @dest. The total size of @dest won't exceed
- dest_size  Caveat: this is supposedly a more secure alternative to strcat() or
-strncat(), but for real security g_strconcat() is harder to mess up.
+
 </para>
 
- dest: destination buffer, already containing one nul-terminated string
- src: source buffer
- dest_size: length of @dest buffer in bytes (not length of existing string inside @dest)
- Returns: length of @src plus initial length of string in @dest
+ dest: 
+ src: 
+ dest_size:
+ Returns: 
 
 
 <!-- ##### FUNCTION g_strdup_printf ##### -->
 <para>
-Similar to the standard C sprintf() function
-but safer, since it calculates the maximum space required and allocates
-memory to hold the result.
-The returned string should be freed when no longer needed.
 </para>
 
- format: a standard printf() format string, but notice 
-  <link linkend="string-precision">string precision pitfalls</link>.
- Varargs: the parameters to insert into the format string.
- Returns: a newly-allocated string holding the result.
+ format: 
+ Varargs: 
+ Returns:
 
 
 <!-- ##### FUNCTION g_strdup_vprintf ##### -->
 <para>
-Similar to the standard C vsprintf() function
-but safer, since it calculates the maximum space required and allocates
-memory to hold the result.
-The returned string should be freed when no longer needed.
-</para>
-<para>
-See also g_vasprintf(), which offers the same functionality, but additionally
-returns the length of the allocated string. 
+
 </para>
 
- format: a standard printf() format string, but notice 
-  <link linkend="string-precision">string precision pitfalls</link>.
- args: the list of parameters to insert into the format string.
- Returns: a newly-allocated string holding the result.
+ format:
+ args: 
+ Returns:
 
 
 <!-- ##### FUNCTION g_printf ##### -->
@@ -637,16 +613,11 @@
 
 <!-- ##### FUNCTION g_strreverse ##### -->
 <para>
-Reverses all of the bytes in a string.
-For example, <literal>g_strreverse ("abcdef")</literal> will result in "fedcba".
-</para>
-<para>
-Note that g_strreverse() doesn't work on UTF-8 strings containing multibyte characters. 
-For that purpose, use g_utf8_strreverse().
+
 </para>
 
- string: the string to reverse.
- Returns: the same pointer passed in as @string.
+ string:
+ Returns:
 
 
 <!-- ##### FUNCTION g_ascii_strtoll ##### -->
@@ -872,43 +843,32 @@
 
 <!-- ##### FUNCTION g_strconcat ##### -->
 <para>
-Concatenates all of the given strings into one long string.  The returned string
-should be freed when no longer needed.  
+
 </para>
 
-<warning><para>
-The variable argument list <emphasis>must</emphasis> end with %NULL. 
-If you forget the %NULL, g_strconcat() will start appending
-random memory junk to your string.
-</para></warning>
-
- string1: The first string to add, which must not be %NULL.
- Varargs: a %NULL-terminated list of strings to append to the string.
- Returns: a newly-allocated string containing all the string arguments.
+ string1: 
+ Varargs:
+ Returns:
 
 
 <!-- ##### FUNCTION g_strjoin ##### -->
 <para>
-Joins a number of strings together to form one long string, with the optional
- separator inserted between each of them.
+
 </para>
 
- separator: a string to insert between each of the strings, or %NULL.
- Varargs: a %NULL-terminated list of strings to join.
- Returns: a newly-allocated string containing all of the strings joined
-together, with @separator between them.
+ separator: 
+ Varargs: 
+ Returns:
 
 
 <!-- ##### FUNCTION g_strjoinv ##### -->
 <para>
-Joins a number of strings together to form one long string, with the optional
- separator inserted between each of them.
+
 </para>
 
- separator: a string to insert between each of the strings, or %NULL.
- str_array: a %NULL-terminated array of strings to join.
- Returns: a newly-allocated string containing all of the strings joined
-together, with @separator between them.
+ separator: 
+ str_array: 
+ Returns:
 
 
 <!-- ##### FUNCTION g_strv_length ##### -->
@@ -922,31 +882,18 @@
 
 <!-- ##### FUNCTION g_strerror ##### -->
 <para>
-Returns a string corresponding to the given error code, e.g. "no such process".
-You should use this function in preference to strerror(), because it returns a
-string in UTF-8 encoding, and since not all platforms support the 
-strerror() function.
+
 </para>
 
- errnum: the system error number. See the standard C %errno
-documentation.
- Returns: a UTF-8 string describing the error code.
-If the error code is unknown, it returns "unknown error (&lt;code&gt;)".
-The string can only be used until the next call to g_strerror().
+ errnum: 
+ Returns: 
 
 
 <!-- ##### FUNCTION g_strsignal ##### -->
 <para>
-Returns a string describing the given signal, e.g. "Segmentation fault".
-You should use this function in preference to strsignal(), because it returns a
-string in UTF-8 encoding, and since not all platforms support the
-strsignal() function.
-</para>
 
- signum: the signal number. See the <literal>signal</literal>
-documentation.
- Returns: a UTF-8 string describing the signal.
-If the signal is unknown, it returns "unknown signal (&lt;signum&gt;)".
-The string can only be used until the next call to g_strsignal().
+</para>
 
+ signum: 
+ Returns:
 

Modified: trunk/glib/gstrfuncs.c
==============================================================================
--- trunk/glib/gstrfuncs.c	(original)
+++ trunk/glib/gstrfuncs.c	Sat Jan  3 04:15:17 2009
@@ -80,6 +80,16 @@
 
 const guint16 * const g_ascii_table = ascii_table_data;
 
+/**
+ * g_strdup:
+ * @str: the string to duplicate
+ *
+ * Duplicates a string. If @str is %NULL it returns %NULL.
+ * The returned string should be freed with g_free() 
+ * when no longer needed.
+ * 
+ * Returns: a newly-allocated copy of @str
+ */
 gchar*
 g_strdup (const gchar *str)
 {
@@ -209,6 +219,22 @@
 #endif
 }
 
+/**
+ * g_strdup_vprintf:
+ * @format: a standard printf() format string, but notice
+ *     <link linkend="string-precision">string precision pitfalls</link>
+ * @args: the list of parameters to insert into the format string
+ * 
+ * Similar to the standard C vsprintf() function but safer, since it 
+ * calculates the maximum space required and allocates memory to hold 
+ * the result. The returned string should be freed with g_free() when 
+ * no longer needed.
+ *
+ * See also g_vasprintf(), which offers the same functionality, but 
+ * additionally returns the length of the allocated string.
+ *
+ * Returns: a newly-allocated string holding the result
+ */
 gchar*
 g_strdup_vprintf (const gchar *format,
 		  va_list      args)
@@ -220,6 +246,19 @@
   return string;
 }
 
+/**
+ * g_strdup_printf:
+ * format: a standard printf() format string, but notice
+ *     <link linkend="string-precision">string precision pitfalls</link>
+ * @Varargs: the parameters to insert into the format string
+ *
+ * Similar to the standard C sprintf() function but safer, since it 
+ * calculates the maximum space required and allocates memory to hold 
+ * the result. The returned string should be freed with g_free() when no 
+ * longer needed.
+ * 
+ * Returns: a newly-allocated string holding the result
+ */
 gchar*
 g_strdup_printf (const gchar *format,
 		 ...)
@@ -234,6 +273,21 @@
   return buffer;
 }
 
+/**
+ * g_strconcat:
+ * @string1: the first string to add, which must not be %NULL
+ * @Varargs: a %NULL-terminated list of strings to append to the string
+ * 
+ * Concatenates all of the given strings into one long string.
+ * The returned string should be freed with g_free() when no longer needed.
+ *
+ *
+ * <warning><para>The variable argument list <emphasis>must</emphasis> end 
+ * with %NULL. If you forget the %NULL, g_strconcat() will start appending
+ * random memory junk to your string.</para></warning>
+ *
+ * Returns: a newly-allocated string containing all the string arguments
+ */
 gchar*
 g_strconcat (const gchar *string1, ...)
 {
@@ -550,7 +604,7 @@
  * string, use g_ascii_dtostr().
  *
  * Return value: The pointer to the buffer with the converted string.
- **/
+ */
 gchar *
 g_ascii_formatd (gchar       *buffer,
 		 gint         buf_len,
@@ -783,7 +837,7 @@
  * Return value: the #guint64 value or zero on error.
  *
  * Since: 2.2
- **/
+ */
 guint64
 g_ascii_strtoull (const gchar *nptr,
 		  gchar      **endptr,
@@ -825,7 +879,7 @@
  * Return value: the #gint64 value or zero on error.
  *
  * Since: 2.12
- **/
+ */
 gint64 
 g_ascii_strtoll (const gchar *nptr,
 		 gchar      **endptr,
@@ -852,6 +906,20 @@
     return (gint64) result;
 }
 
+/**
+ * g_strerror:
+ * @errnum: the system error number. See the standard C %errno
+ *     documentation
+ * 
+ * Returns a string corresponding to the given error code, e.g. 
+ * "no such process". You should use this function in preference to 
+ * strerror(), because it returns a string in UTF-8 encoding, and since 
+ * not all platforms support the strerror() function.
+ *
+ * Returns: a UTF-8 string describing the error code. If the error code 
+ *     is unknown, it returns "unknown error (&lt;code&gt;)". The string 
+ *     can only be used until the next call to g_strerror()
+ */
 G_CONST_RETURN gchar*
 g_strerror (gint errnum)
 {
@@ -1319,6 +1387,20 @@
   return msg;
 }
 
+/**
+ * g_strsignal:
+ * @signum: the signal number. See the <literal>signal</literal>
+ *     documentation
+ *
+ * Returns a string describing the given signal, e.g. "Segmentation fault".
+ * You should use this function in preference to strsignal(), because it 
+ * returns a string in UTF-8 encoding, and since not all platforms support
+ * the strsignal() function.
+ *
+ * Returns: a UTF-8 string describing the signal. If the signal is unknown,
+ *     it returns "unknown signal (&lt;signum&gt;)". The string can only be 
+ *     used until the next call to g_strsignal()
+ */ 
 G_CONST_RETURN gchar*
 g_strsignal (gint signum)
 {
@@ -1499,14 +1581,28 @@
 }
 
 #else /* ! HAVE_STRLCPY */
-/* g_strlcpy
+/**
+ * g_strlcpy:
+ * @dest: destination buffer
+ * @src: source buffer
+ * @dest_size: length of @dest in bytes
+ * 
+ * Portability wrapper that calls strlcpy() on systems which have it, 
+ * and emulates strlcpy() otherwise. Copies @src to @dest; @dest is 
+ * guaranteed to be nul-terminated; @src must be nul-terminated; 
+ * @dest_size is the buffer size, not the number of chars to copy. 
+ *
+ * At most dest_size - 1 characters will be copied. Always nul-terminates
+ * (unless dest_size == 0). This function does <emphasis>not</emphasis> 
+ * allocate memory. Unlike strncpy(), this function doesn't pad dest (so 
+ * it's often faster). It returns the size of the attempted result, 
+ * strlen (src), so if @retval >= @dest_size, truncation occurred.
+ * 
+ * <note><para>Caveat: strlcpy() is supposedly more secure than
+ * strcpy() or strncpy(), but if you really want to avoid screwups, 
+ * g_strdup() is an even better idea.</para></note>
  *
- * Copy string src to buffer dest (of buffer size dest_size).  At most
- * dest_size-1 characters will be copied.  Always NUL terminates
- * (unless dest_size == 0).  This function does NOT allocate memory.
- * Unlike strncpy, this function doesn't pad dest (so it's often faster).
- * Returns size of attempted result, strlen(src),
- * so if retval >= dest_size, truncation occurred.
+ * Returns: length of @src
  */
 gsize
 g_strlcpy (gchar       *dest,
@@ -1544,10 +1640,19 @@
   return s - src - 1;  /* count does not include NUL */
 }
 
-/* g_strlcat
+/**
+ * g_strlcat:
+ * @dest: destination buffer, already containing one nul-terminated string
+ * @src: source buffer
+ * @dest_size: length of @dest buffer in bytes (not length of existing string 
+ *     inside @dest)
+ *
+ * Portability wrapper that calls strlcat() on systems which have it, 
+ * and emulates it otherwise. Appends nul-terminated @src string to @dest, 
+ * guaranteeing nul-termination for @dest. The total size of @dest won't 
+ * exceed @dest_size. 
  *
- * Appends string src to buffer dest (of buffer size dest_size).
- * At most dest_size-1 characters will be copied.
+ * At most dest_size - 1 characters will be copied.
  * Unlike strncat, dest_size is the full size of dest, not the space left over.
  * This function does NOT allocate memory.
  * This always NUL terminates (unless siz == 0 or there were no NUL characters
@@ -1555,6 +1660,11 @@
  * Returns size of attempted result, which is
  * MIN (dest_size, strlen (original dest)) + strlen (src),
  * so if retval >= dest_size, truncation occurred.
+ *
+ * <note><para>Caveat: this is supposedly a more secure alternative to 
+ * strcat() or strncat(), but for real security g_strconcat() is harder 
+ * to mess up.</para></note>
+ *
  */
 gsize
 g_strlcat (gchar       *dest,
@@ -1716,6 +1826,20 @@
   return (gchar *) string;
 }
 
+/**
+ * g_strreverse:
+ * @string: the string to reverse 
+ *
+ * Reverses all of the bytes in a string. For example, 
+ * <literal>g_strreverse ("abcdef")</literal> will result 
+ * in "fedcba".
+ * 
+ * Note that g_strreverse() doesn't work on UTF-8 strings 
+ * containing multibyte characters. For that purpose, use 
+ * g_utf8_strreverse().
+ * 
+ * Returns: the same pointer passed in as @string
+ */
 gchar*
 g_strreverse (gchar *string)
 {
@@ -2476,6 +2600,18 @@
     return NULL;
 }
 
+/**
+ * g_strjoinv:
+ * @separator: a string to insert between each of the strings, or %NULL
+ * @str_array: a %NULL-terminated array of strings to join
+ * 
+ * Joins a number of strings together to form one long string, with the 
+ * optional @separator inserted between each of them. The returned string
+ * should be freed with g_free().
+ *
+ * Returns: a newly-allocated string containing all of the strings joined
+ *     together, with @separator between them
+ */
 gchar*
 g_strjoinv (const gchar  *separator,
 	    gchar       **str_array)
@@ -2516,6 +2652,18 @@
   return string;
 }
 
+/**
+ * g_strjoin:
+ * @separator: a string to insert between each of the strings, or %NULL
+ * @Varargs: a %NULL-terminated list of strings to join
+ *
+ * Joins a number of strings together to form one long string, with the 
+ * optional @separator inserted between each of them. The returned string
+ * should be freed with g_free().
+ *
+ * Returns: a newly-allocated string containing all of the strings joined
+ *     together, with @separator between them
+ */
 gchar*
 g_strjoin (const gchar  *separator,
 	   ...)