[PATCH] small improvements to GLib API docs

[Davyd Madeley-3]

This bit two people yesterday (one of them was me) in wondering how
g_strchomp and g_strchug actually worked. Did it allocate memory, did it
return different pointers, would I have to keep another pointer around.
Stuff like that.

I added a couple of sentences and some cross referencing (because the
functions aren't entirely clearly named) in an attempt to clear this up.

--d

PS. CC me, I'm off list.

[glib-doc-additions.diff]

---

? glib-doc-additions.diff
Index: docs/reference/glib/tmpl/string_utils.sgml
===================================================================
RCS file: /cvs/gnome/glib/docs/reference/glib/tmpl/string_utils.sgml,v
retrieving revision 1.40
diff -u -p -r1.40 string_utils.sgml
--- docs/reference/glib/tmpl/string_utils.sgml 5 May 2005 14:57:27 -0000 1.40
+++ docs/reference/glib/tmpl/string_utils.sgml 30 Sep 2005 04:46:03 -0000
@@ -722,6 +722,13 @@ The typical usage would be something lik
 Removes leading whitespace from a string, by moving the rest of the
 characters forward.
 </para>
+<para>
+This function doesn't allocate or reallocate any memory; it modifies @string
+in place. The pointer to @string is returned to allow the nesting of functions.
+</para>
+<para>
+Also see g_strchomp() and g_strstrip().
+</para>
 
 @string: a string to remove the leading whitespace from.
 @Returns: @string.
@@ -731,6 +738,13 @@ characters forward.
 <para>
 Removes trailing whitespace from a string.
 </para>
+<para>
+This function doesn't allocate or reallocate any memory; it modifies @string in
+place. The pointer to @string is return to allow the nesting of functions.
+</para>
+<para>
+Also see g_strchug() and g_strstrip().
+</para>
 
 @string: a string to remove the trailing whitespace from.
 @Returns: @string.
@@ -738,7 +752,8 @@ Removes trailing whitespace from a strin
 
 <!-- ##### MACRO g_strstrip ##### -->
 <para>
-Removes leading and trailing whitespace from a string.
+Removes leading and trailing whitespace from a string. See g_strchomp() and
+g_strchug().
 </para>
 
 @string: a string to remove the leading and trailing whitespace from.

---

_______________________________________________
gtk-devel-list mailing list
gtk-devel-list@...
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

[Matthias Clasen]

On Fri, 2005-09-30 at 12:55 +0800, Davyd Madeley wrote:
> This bit two people yesterday (one of them was me) in wondering how
> g_strchomp and g_strchug actually worked. Did it allocate memory, did it
> return different pointers, would I have to keep another pointer around.
> Stuff like that.
>
> I added a couple of sentences and some cross referencing (because the
> functions aren't entirely clearly named) in an attempt to clear this up.
>

Hmm, "Returns: @string" is supposed to convey that the function does not
return any newly allocated memory, but maybe it is a little terse.

Feel free to commit your doc additions after fixing the grammar ("is
return" should be "is returned").


Regards, Matthias

_______________________________________________
gtk-devel-list mailing list
gtk-devel-list@...
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

[Behdad Esfahbod]

On Fri, 30 Sep 2005, Matthias Clasen wrote:

> On Fri, 2005-09-30 at 12:55 +0800, Davyd Madeley wrote:
> > This bit two people yesterday (one of them was me) in wondering how
> > g_strchomp and g_strchug actually worked. Did it allocate memory, did it
> > return different pointers, would I have to keep another pointer around.
> > Stuff like that.
> >
> > I added a couple of sentences and some cross referencing (because the
> > functions aren't entirely clearly named) in an attempt to clear this up.
> >
>
> Hmm, "Returns: @string" is supposed to convey that the function does not
> return any newly allocated memory, but maybe it is a little terse.
>
> Feel free to commit your doc additions after fixing the grammar ("is
> return" should be "is returned").

I prefer not saying "it doesn't allocate or reallocate".  Just
say it edits @string in place.



> Regards, Matthias
--behdad
http://behdad.org/
_______________________________________________
gtk-devel-list mailing list
gtk-devel-list@...
http://mail.gnome.org/mailman/listinfo/gtk-devel-list