[libgsf] Docs: introspection fixes.

[Morten Welinder <mortenw src gnome org>]

commit 8eeb0fee93bcbb960f76490c0695bb9df70e1160
Author: Morten Welinder <terra gnome org>
Date:   Thu Mar 7 19:39:44 2013 -0500

    Docs: introspection fixes.

 gsf/gsf-doc-meta-data.c  |    5 ++---
 gsf/gsf-input.c          |   24 +++++++++++++++++++++++-
 gsf/gsf-libxml.c         |    6 +++---
 gsf/gsf-open-pkg-utils.c |   13 +++++++------
 gsf/gsf-output.c         |   23 +++++++++++++++++++++++
 gsf/gsf-utils.c          |    6 +++---
 6 files changed, 61 insertions(+), 16 deletions(-)
---
diff --git a/gsf/gsf-doc-meta-data.c b/gsf/gsf-doc-meta-data.c
index faab9ef..c844523 100644
--- a/gsf/gsf-doc-meta-data.c
+++ b/gsf/gsf-doc-meta-data.c
@@ -334,7 +334,7 @@ gsf_doc_prop_get_type (void)
  * gsf_doc_prop_get_name:
  * @prop: #GsfDocProp
  *
- * Returns: the name of the property, the caller should not modify the result.
+ * Returns: (transfer none): the name of the property
  **/
 char const *
 gsf_doc_prop_get_name (GsfDocProp const *prop)
@@ -400,8 +400,7 @@ gsf_doc_prop_swap_val (GsfDocProp *prop, GValue *val)
  * gsf_doc_prop_get_link:
  * @prop: #GsfDocProp
  *
- * Returns: the current link descriptor of @prop.  The result should not be
- *     freed or modified.
+ * Returns: (transfer none): the current link descriptor of @prop.
  **/
 char const *
 gsf_doc_prop_get_link (GsfDocProp const *prop)
diff --git a/gsf/gsf-input.c b/gsf/gsf-input.c
index bacfc5b..aeb1c4b 100644
--- a/gsf/gsf-input.c
+++ b/gsf/gsf-input.c
@@ -127,6 +127,11 @@ gsf_input_class_init (GObjectClass *gobject_class)
                                      GSF_PARAM_STATIC |
                                      G_PARAM_READABLE));
 
+       /**
+        * GsfInput:size:
+        *
+        * The total number of bytes in the file.
+        */
        g_object_class_install_property
                (gobject_class,
                 PROP_SIZE,
@@ -140,7 +145,7 @@ gsf_input_class_init (GObjectClass *gobject_class)
        /**
         * GsfInput:eof:
         *
-        * True if the end of the file has been reached.
+        * %TRUE if the end of the file has been reached.
         */
        g_object_class_install_property
                (gobject_class,
@@ -152,6 +157,11 @@ gsf_input_class_init (GObjectClass *gobject_class)
                                       GSF_PARAM_STATIC |
                                       G_PARAM_READABLE));
 
+       /**
+        * GsfInput:remaining:
+        *
+        * The number of bytes remaining in the file.
+        */
        g_object_class_install_property
                (gobject_class,
                 PROP_REMAINING,
@@ -162,6 +172,11 @@ gsf_input_class_init (GObjectClass *gobject_class)
                                     GSF_PARAM_STATIC |
                                     G_PARAM_READABLE));
 
+       /**
+        * GsfInput:position:
+        *
+        * The current position in the input.
+        */
        g_object_class_install_property
                (gobject_class,
                 PROP_POS,
@@ -172,6 +187,13 @@ gsf_input_class_init (GObjectClass *gobject_class)
                                     GSF_PARAM_STATIC |
                                     G_PARAM_READABLE));
 
+       /**
+        * GsfInput:modtime:
+        *
+        * The time the input was last updated.  This represents the
+        * timestamp from the originating file or @GsfInfile member.
+        * It is not supported by all derived classes.
+        */
        g_object_class_install_property
                (gobject_class,
                 PROP_MODTIME,
diff --git a/gsf/gsf-libxml.c b/gsf/gsf-libxml.c
index b428c1c..f5936c2 100644
--- a/gsf/gsf-libxml.c
+++ b/gsf/gsf-libxml.c
@@ -1329,8 +1329,8 @@ gsf_xml_in_get_input (GsfXMLIn const *xin)
  *
  * According to @state is @str in the namespace @ns_id ?
  *
- * Returns: a pointer to @str after the namespace if successful,
- *     otherwise %NULL.
+ * Returns: (transfer none): a pointer to @str after the namespace if
+ * successful, otherwise %NULL.
  **/
 char const *
 gsf_xml_in_check_ns (GsfXMLIn const *xin, char const *str, unsigned int ns_id)
@@ -1612,7 +1612,7 @@ gsf_xml_out_start_element (GsfXMLOut *xout, char const *id)
  *
  * Closes/ends an XML element.
  *
- * Returns: the element that has been closed.
+ * Returns: (transfer none): the element that has been closed.
  */
 char const *
 gsf_xml_out_end_element (GsfXMLOut *xout)
diff --git a/gsf/gsf-open-pkg-utils.c b/gsf/gsf-open-pkg-utils.c
index 30a546e..e9bcd0c 100644
--- a/gsf/gsf-open-pkg-utils.c
+++ b/gsf/gsf-open-pkg-utils.c
@@ -126,7 +126,7 @@ gsf_open_pkg_rel_is_extern (GsfOpenPkgRel const *rel)
  * gsf_open_pkg_rel_get_target:
  * @rel: #GsfOpenPkgRel
  *
- * Returns: const pointer to @rel's target.
+ * Returns: (transfer none): The target of @rel.
  **/
 char const *
 gsf_open_pkg_rel_get_target (GsfOpenPkgRel const *rel)
@@ -139,7 +139,7 @@ gsf_open_pkg_rel_get_target (GsfOpenPkgRel const *rel)
  * gsf_open_pkg_rel_get_type:
  * @rel: #GsfOpenPkgRel
  *
- * Returns: const pointer to @rel's type.
+ * Returns: (transfer none): The type of @rel.
  **/
 char const *
 gsf_open_pkg_rel_get_type (GsfOpenPkgRel const *rel)
@@ -824,8 +824,8 @@ gsf_outfile_open_pkg_create_rel (GsfOutfileOpenPkg *parent,
  *
  * Create a relationship between @child and @parent of @type.
  *
- * Returns: the relID which the caller does not own but will live as long as
- *     @parent.
+ * Returns: (transfer none): the relID which the caller does not own
+ *     but will live as long as @parent.
  **/
 char const *
 gsf_outfile_open_pkg_relate (GsfOutfileOpenPkg *child,
@@ -900,8 +900,9 @@ gsf_outfile_open_pkg_add_rel (GsfOutfile *dir,
  *
  * Add an external relation to @parent.
  *
- * Returns: (transfer none): The id of the relation.  The string is managed by the parent and
- *     should not be changed or freed by the caller.
+ * Returns: (transfer none): The id of the relation.  The string is
+ * managed by the parent and should not be changed or freed by the
+ * caller.
  **/
 char const *
 gsf_outfile_open_pkg_add_extern_rel (GsfOutfileOpenPkg *parent,
diff --git a/gsf/gsf-output.c b/gsf/gsf-output.c
index d82568e..2569b7e 100644
--- a/gsf/gsf-output.c
+++ b/gsf/gsf-output.c
@@ -165,6 +165,11 @@ gsf_output_class_init (GObjectClass *gobject_class)
                                      GSF_PARAM_STATIC |
                                      G_PARAM_READABLE));
 
+       /**
+        * GsfOutput:size:
+        *
+        * The current file size.
+        */
        g_object_class_install_property
                (gobject_class,
                 PROP_SIZE,
@@ -175,6 +180,11 @@ gsf_output_class_init (GObjectClass *gobject_class)
                                     GSF_PARAM_STATIC |
                                     G_PARAM_READABLE));
 
+       /**
+        * GsfOutput:is-closed:
+        *
+        * %TRUE if the output has been closed.
+        */
        g_object_class_install_property
                (gobject_class,
                 PROP_CLOSED,
@@ -185,6 +195,11 @@ gsf_output_class_init (GObjectClass *gobject_class)
                                       GSF_PARAM_STATIC |
                                       G_PARAM_READABLE));
 
+       /**
+        * GsfOutput:position:
+        *
+        * The current position in the output.
+        */
        g_object_class_install_property
                (gobject_class,
                 PROP_POS,
@@ -195,6 +210,14 @@ gsf_output_class_init (GObjectClass *gobject_class)
                                     GSF_PARAM_STATIC |
                                     G_PARAM_READABLE));
 
+       /**
+        * GsfOutput:modtime:
+        *
+        * The time the output was last updated.  This must be set on object
+        * construction and represents the timestamp to put on the resulting
+        * file or #GsfOutfile member.  Not all derived classes will actually
+        * do anything with this property.
+        */
        g_object_class_install_property
                (gobject_class,
                 PROP_MODTIME,
diff --git a/gsf/gsf-utils.c b/gsf/gsf-utils.c
index 92d8dc5..c80c533 100644
--- a/gsf/gsf-utils.c
+++ b/gsf/gsf-utils.c
@@ -537,9 +537,9 @@ gsf_le_set_double (void *p, double d)
  * Extracts the extension from the end of a filename (the part after the final
  * '.' in the filename).
  *
- * Returns: A pointer to the extension part of the filename, or a
- * pointer to the end of the string if the filename does not
- * have an extension.
+ * Returns: (transfer none): A pointer to the extension part of the
+ * filename, or a pointer to the end of the string if the filename
+ * does not have an extension.
  */
 char const *
 gsf_extension_pointer (char const *path)