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)

diff --git a/ChangeLog b/ChangeLog
index 4fabc02..1833286 100644 (file)
--- a/ChangeLog
+++ b/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)
 

diff --git a/docs/reference/glib/tmpl/string_utils.sgml b/docs/reference/glib/tmpl/string_utils.sgml
index f744d5d..8d9a8be 100644 (file)
--- a/docs/reference/glib/tmpl/string_utils.sgml
+++ b/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.
-@n: the maximum number of characters to copy from @str.
-@Returns: a newly-allocated buffer containing the first @n characters of @str,
-nul-terminated.
+@str: 
+@n: 
+@Returns: 
 
 
 <!-- ##### 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.
-@fill_char: the character to fill the string with.
-@Returns: a newly-allocated string filled the @fill_char.
+@length: 
+@fill_char:
+@Returns: 
 
 
 <!-- ##### FUNCTION g_stpcpy ##### -->

diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c
index 61d11ed..7ab4d64 100644 (file)
--- a/glib/gstrfuncs.c
+++ b/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)