[libgsf] Doc improvements.

[Morten Welinder <mortenw src gnome org>]

commit f42edcad2b6f259c1caf46366b7a9c6ca3599e87
Author: Morten Welinder <terra gnome org>
Date:   Sat Feb 23 17:39:27 2013 -0500

    Doc improvements.

 ChangeLog        |    4 ++++
 NEWS             |    1 +
 gsf/gsf-infile.c |   20 +++++++++++++++++++-
 3 files changed, 24 insertions(+), 1 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index b49f756..586649f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2013-02-23  Morten Welinder  <terra gnome org>
 
+       * gsf/gsf-infile.c (gsf_infile_child_by_name)
+       (gsf_infile_child_by_vname, gsf_infile_child_by_vaname)
+       (gsf_infile_child_by_aname): Doc improvements.
+
        * gsf/gsf-input.c (gsf_input_uncompress): Avoid HAVE_BZ2
        conditionals.
 
diff --git a/NEWS b/NEWS
index 9f8112d..7c3c772 100644
--- a/NEWS
+++ b/NEWS
@@ -13,6 +13,7 @@ Morten:
        * Clean out old glib tests.
        * Speed up ole writing a bit.
        * Header cleanup.  gsf/gsf.h is now main header.  [#684608]
+       * GsfInput doc improvements.  [#540521]
 
 Paolo Bonzini:
        * Fix gsf_input_dep for msole streams.  [#689706]
diff --git a/gsf/gsf-infile.c b/gsf/gsf-infile.c
index 550bce9..8ad1a10 100644
--- a/gsf/gsf-infile.c
+++ b/gsf/gsf-infile.c
@@ -92,8 +92,14 @@ gsf_infile_child_by_index (GsfInfile *infile, int i)
  * @infile: #GsfInfile
  * @name: target name
  *
+ * The function returns a named child of the given infile.  This only
+ * works for an immediate child.  If you need to go several levels
+ * down use gsf_infile_child_by_aname, for example.
+ *
  * TODO : For 2.0 api will change to include a GError.
- * Returns: (transfer full): a newly created child which must be unrefed.
+ *
+ * Returns: (transfer full): a newly created child which must be
+ * unrefed.
  **/
 GsfInput *
 gsf_infile_child_by_name (GsfInfile *infile, char const *name)
@@ -122,6 +128,9 @@ gsf_infile_child_by_name (GsfInfile *infile, char const *name)
  * @infile:
  * @...: A %NULL terminated list of names
  *
+ * Apart from the way arguments are specified, this is the same as
+ * gsf_infile_child_by_aname.  Please see the documentation there.
+ *
  * Returns: (transfer full): a newly created child which must be unrefed.
  **/
 GsfInput *
@@ -142,6 +151,8 @@ gsf_infile_child_by_vname (GsfInfile *infile,  ...)
  * @infile: #GsfInfile
  * @names: A %NULL terminated array of names (e.g. from g_strsplit)
  *
+ * Apart from argument types, this is the same as gsf_infile_child_by_aname.
+ * Please see the documentation there.
  * New in 1.14.9.
  *
  * Returns: (transfer full): a newly created child which must be unrefed.
@@ -175,6 +186,13 @@ gsf_infile_child_by_vaname (GsfInfile *infile, va_list names)
  * @infile: #GsfInfile
  * @names: A %NULL terminated array of names (e.g. from g_strsplit)
  *
+ * This function finds a child that is several directory levels down
+ * the tree.  If, for example, the names "foo", "bar", and "baz" are
+ * given, then this function first finds the "foo" directory in the
+ * root infile, then locates "bar" within that directory, and finally
+ * locates "baz" within that and returns the "baz" child.  In other
+ * words, this function finds the "foo/bar/baz" child.
+ *
  * New in 1.14.9.
  *
  * Returns: (transfer full): a newly created child which must be unrefed.