Move docs inline, and improve wording. (#372598, Behdad Esfahbod)

2006-12-17  Matthias Clasen  <mclasen@redhat.com>

        * glib/gstrfuncs.c (g_strndup, g_strnfill): Move docs
        inline, and improve wording.  (#372598, Behdad Esfahbod)

ChangeLog

@@ -1,5 +1,8 @@
 2006-12-17  Matthias Clasen  <mclasen@redhat.com>
 
+	* glib/gstrfuncs.c (g_strndup, g_strnfill): Move docs
+	inline, and improve wording.  (#372598, Behdad Esfahbod)
+
 	* glib/gspawn.c: Add some pointers to the gdk_spawn_
 	variants.  (#338134, Federico Mena Quintero)
 

docs/reference/glib/tmpl/string_utils.sgml

@@ -53,17 +53,12 @@ The returned string should be freed when no longer needed.
 
 <!-- ##### FUNCTION g_strndup ##### -->
 <para>
-Duplicates the first @n characters of a string, returning a newly-allocated
+
-buffer @n + 1 characters long which will always be nul-terminated.
-If @str is less than @n characters long the buffer is padded with nuls.
-If @str is %NULL it returns %NULL.
-The returned value should be freed when no longer needed.
 </para>
 
-@str: the string to duplicate part of.
+@str: 
-@n: the maximum number of characters to copy from @str.
+@n: 
-@Returns: a newly-allocated buffer containing the first @n characters of @str,
+@Returns: 
-nul-terminated.
 
 
 <!-- ##### FUNCTION g_strdupv ##### -->
@@ -76,13 +71,12 @@ nul-terminated.
 
 <!-- ##### FUNCTION g_strnfill ##### -->
 <para>
-Creates a new string @length characters long filled with @fill_char.
+
-The returned string should be freed when no longer needed.
 </para>
 
-@length: the length of the new string.
+@length: 
-@fill_char: the character to fill the string with.
+@fill_char:
-@Returns: a newly-allocated string filled the @fill_char.
+@Returns: 
 
 
 <!-- ##### FUNCTION g_stpcpy ##### -->

glib/gstrfuncs.c

@@ -114,6 +114,25 @@ g_memdup (gconstpointer mem,
   return new_mem;
 }
 
+/**
+ * g_strndup:
+ * @str: the string to duplicate
+ * @n: the maximum number of bytes to copy from @str
+ *
+ * Duplicates the first @n bytes of a string, returning a newly-allocated
+ * buffer @n + 1 bytes long which will always be nul-terminated.
+ * If @str is less than @n bytes long the buffer is padded with nuls.
+ * If @str is %NULL it returns %NULL.
+ * The returned value should be freed when no longer needed.
+ * 
+ * <note><para>
+ * To copy a number of characters from a UTF-8 encoded string, use
+ * g_utf8_strncpy() instead.
+ * </para></note>
+ * 
+ * Returns: a newly-allocated buffer containing the first @n bytes 
+ *          of @str, nul-terminated 
+ */
 gchar*
 g_strndup (const gchar *str,
 	   gsize        n)    
@@ -132,6 +151,16 @@ g_strndup (const gchar *str,
   return new_str;
 }
 
+/**
+ * g_strnfill:
+ * @length: the length of the new string
+ * @fill_char: the byte to fill the string with
+ *
+ * Creates a new string @length bytes long filled with @fill_char.
+ * The returned string should be freed when no longer needed.
+ * 
+ * Returns: a newly-allocated string filled the @fill_char
+ */
 gchar*
 g_strnfill (gsize length,     
 	    gchar fill_char)