[libgsf] Introspection fixes.

From: Morten Welinder <mortenw src gnome org>
To: commits-list gnome org
Cc:
Subject: [libgsf] Introspection fixes.
Date: Wed, 11 Apr 2018 00:13:40 +0000 (UTC)
commit b5b2ff66caf9d69a5ee0ef17a178134762ae1300
Author: Morten Welinder <terra gnome org>
Date:   Tue Apr 10 20:13:04 2018 -0400

    Introspection fixes.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=794777

 ChangeLog                |    6 ++++++
 NEWS                     |    3 +++
 gsf/Makefile.am          |    3 ++-
 gsf/gsf-doc-meta-data.c  |   20 ++++++++++----------
 gsf/gsf-infile-msvba.c   |   11 ++++++-----
 gsf/gsf-infile.c         |    4 ++--
 gsf/gsf-input-impl.h     |    2 +-
 gsf/gsf-input-memory.c   |    6 +++---
 gsf/gsf-input-textline.c |    6 +++---
 gsf/gsf-input.c          |   24 ++++++++++++------------
 gsf/gsf-libxml.c         |   40 ++++++++++++++++++++--------------------
 gsf/gsf-opendoc-utils.c  |    2 +-
 gsf/gsf-outfile.c        |    2 +-
 gsf/gsf-output-memory.c  |    4 ++--
 gsf/gsf-output.c         |   18 +++++++++---------
 gsf/gsf-utils.c          |   39 +++++++++++++++++++++++++--------------
 16 files changed, 106 insertions(+), 84 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index e10ba9d..8586b71 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2018-04-10  Morten Welinder  <terra gnome org>
+
+       * gsf/*.c: various introspection fixes, mostly from bug 794777 by
+       Corentin Noël and Rico Tzschichholz.  The occasional extra fix by
+       me.
+
 2018-03-22  Morten Welinder  <terra gnome org>
 
        * gsf/gsf-input-memory.c (gsf_input_mmap_new): Set modtime.
diff --git a/NEWS b/NEWS
index 2a2a6ac..cfff7ae 100644
--- a/NEWS
+++ b/NEWS
@@ -3,6 +3,9 @@ libgsf 1.14.43
 Morten:
        * Handle modtime for memory mapped files.
 
+Corentin No�l and Rico Tzschichholz:
+       * Introspection fixes.
+
 --------------------------------------------------------------------------
 libgsf 1.14.42
 
diff --git a/gsf/Makefile.am b/gsf/Makefile.am
index a2e271d..d0a9d46 100644
--- a/gsf/Makefile.am
+++ b/gsf/Makefile.am
@@ -7,7 +7,8 @@ include $(top_srcdir)/gsf.mk
 -include $(INTROSPECTION_MAKEFILE)
 INTROSPECTION_GIRS =
 INTROSPECTION_SCANNER_ARGS = \
-       -v --warn-all --accept-unprefixed -DGSF_DISABLE_DEPRECATED
+       -v --warn-all --accept-unprefixed -DGSF_DISABLE_DEPRECATED \
+       --c-include=gsf/gsf.h
 INTROSPECTION_COMPILER_ARGS = \
        --includedir=$(srcdir) \
     --includedir=.
diff --git a/gsf/gsf-doc-meta-data.c b/gsf/gsf-doc-meta-data.c
index 46d0d97..b0b4ac8 100644
--- a/gsf/gsf-doc-meta-data.c
+++ b/gsf/gsf-doc-meta-data.c
@@ -1,4 +1,3 @@
-/* vim: set sw=8: -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
 /*
  * gsf-doc-meta-data.c:
  *
@@ -87,8 +86,8 @@ gsf_doc_meta_data_new (void)
  * @meta: #GsfDocMetaData
  * @name:
  *
- * Returns: the property with name @id in @meta.  The caller can modify the
- * property value and link but not the name.
+ * Returns: (nullable) (transfer none): the property with @name in @meta.  The caller can
+ * modify the property value and link but not the name.
  **/
 GsfDocProp *
 gsf_doc_meta_data_lookup (GsfDocMetaData const *meta, char const *name)
@@ -101,8 +100,8 @@ gsf_doc_meta_data_lookup (GsfDocMetaData const *meta, char const *name)
 /**
  * gsf_doc_meta_data_insert:
  * @meta: #GsfDocMetaData
- * @name: the id.
- * @value: #GValue
+ * @name: (transfer full): the id.
+ * @value: (transfer full): #GValue
  *
  * Take ownership of @name and @value and insert a property into @meta.
  * If a property exists with @name, it is replaced (The link is lost)
@@ -143,6 +142,7 @@ gsf_doc_meta_data_remove (GsfDocMetaData *meta, char const *name)
  * @meta: #GsfDocMetaData
  * @name:
  *
+ * Returns: (nullable) (transfer full): the property with @name in @meta.
  **/
 GsfDocProp *
 gsf_doc_meta_data_steal (GsfDocMetaData *meta, char const *name)
@@ -188,7 +188,7 @@ deref_strcmp (const char **a, const char **b)
  * gsf_doc_meta_data_foreach:
  * @meta: the collection
  * @func: (scope call): the function called once for each element in the collection
- * @user_data: any supplied user data or %NULL
+ * @user_data: (nullable): any supplied user data
  *
  * Iterate through each (key, value) pair in this collection
  **/
@@ -285,9 +285,9 @@ gsf_doc_prop_new (char *name)
 
 /**
  * gsf_doc_prop_free:
- * @prop: (allow-none): #GsfDocProp
+ * @prop: (transfer full) (allow-none): #GsfDocProp
  *
- * If @prop is non %NULL free the memory associated with it
+ * Release the given property.
  **/
 void
 gsf_doc_prop_free (GsfDocProp *prop)
@@ -399,7 +399,7 @@ gsf_doc_prop_swap_val (GsfDocProp *prop, GValue *val)
  * gsf_doc_prop_get_link:
  * @prop: #GsfDocProp
  *
- * Returns: (transfer none): the current link descriptor of @prop.
+ * Returns: (transfer none) (nullable): the current link descriptor of @prop.
  **/
 char const *
 gsf_doc_prop_get_link (GsfDocProp const *prop)
@@ -411,7 +411,7 @@ gsf_doc_prop_get_link (GsfDocProp const *prop)
 /**
  * gsf_doc_prop_set_link:
  * @prop: #GsfDocProp
- * @link: (transfer full): optionally %NULL
+ * @link: (transfer full) (nullable): a link.
  *
  * Sets @prop's link to @link
  **/
diff --git a/gsf/gsf-infile-msvba.c b/gsf/gsf-infile-msvba.c
index 6dbdea0..8b2b499 100644
--- a/gsf/gsf-infile-msvba.c
+++ b/gsf/gsf-infile-msvba.c
@@ -1,4 +1,3 @@
-/* vim: set sw=8: -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
 /*
  * gsf-infile-msvba.c :
  *
@@ -519,7 +518,8 @@ gsf_infile_msvba_new (GsfInfile *source, GError **err)
  *
  * a collection of names and source code.
  *
- * Returns: (transfer none): %NULL, or a hashtable of names and source code (unknown encoding).
+ * Returns: (transfer none) (element-type utf8 gpointer) (nullable):
+ * A #GHashTable of names and source code (unknown encoding).
  **/
 GHashTable *
 gsf_infile_msvba_get_modules (GsfInfileMSVBA const *vba_stream)
@@ -534,7 +534,8 @@ gsf_infile_msvba_get_modules (GsfInfileMSVBA const *vba_stream)
  *
  * A collection of names and source code which the caller is responsible for destroying.
  *
- * Returns: (transfer full): %NULL, or a hashtable of names and source code (unknown encoding).
+ * Returns: (transfer full) (element-type utf8 gpointer) (nullable): A
+ * #GHashTable of names and source code (unknown encoding).
  **/
 GHashTable *
 gsf_infile_msvba_steal_modules (GsfInfileMSVBA *vba_stream)
@@ -549,11 +550,11 @@ gsf_infile_msvba_steal_modules (GsfInfileMSVBA *vba_stream)
 /**
  * gsf_input_find_vba:
  * @input: #GsfInput
- * @err: #GError, optionally %NULL.
+ * @err: (nullable): #GError.
  *
  * A utility routine that attempts to find the VBA file withint a stream.
  *
- * Returns: (transfer full): a GsfInfile
+ * Returns: (transfer full) (nullable): a GsfInfile
  **/
 GsfInfileMSVBA *
 gsf_input_find_vba (GsfInput *input, GError **err)
diff --git a/gsf/gsf-infile.c b/gsf/gsf-infile.c
index 99822bc..2fe5223 100644
--- a/gsf/gsf-infile.c
+++ b/gsf/gsf-infile.c
@@ -47,7 +47,7 @@ gsf_infile_num_children (GsfInfile *infile)
  * @infile: An #GsfInfile
  * @i: zero-based index of child to find.
  *
- * Returns: (transfer none): the utf8 encoded name of the @i-th child
+ * Returns: (transfer none) (nullable): the utf8 encoded name of the @i-th child
  **/
 const gchar *
 gsf_infile_name_by_index (GsfInfile *infile, int i)
@@ -183,7 +183,7 @@ gsf_infile_child_by_vaname (GsfInfile *infile, va_list names)
 /**
  * gsf_infile_child_by_aname:
  * @infile: #GsfInfile
- * @names: A %NULL terminated array of names (e.g. from g_strsplit)
+ * @names: (array zero-terminated=1): 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
diff --git a/gsf/gsf-input-impl.h b/gsf/gsf-input-impl.h
index f33f405..2f08e91 100644
--- a/gsf/gsf-input-impl.h
+++ b/gsf/gsf-input-impl.h
@@ -43,7 +43,7 @@ typedef struct {
        gboolean      (*Seek) (GsfInput *input, gsf_off_t offset,
                               GSeekType whence);
        GsfInput     *(*OpenSibling)  (GsfInput const *input,
-                                      char const *path, GError **err);
+                                      char const *name, GError **err);
 
        /* Padding for future expansion */
        void (*_gsf_reserved0) (void);
diff --git a/gsf/gsf-input-memory.c b/gsf/gsf-input-memory.c
index 351cfc0..9c31170 100644
--- a/gsf/gsf-input-memory.c
+++ b/gsf/gsf-input-memory.c
@@ -53,7 +53,7 @@ typedef GsfInputClass GsfInputMemoryClass;
 
 /**
  * gsf_input_memory_new:
- * @buf: The input bytes
+ * @buf: (array length=length): The input bytes
  * @length: The length of @buf
  * @needs_free: Whether you want this memory to be free'd at object destruction
  *
@@ -70,7 +70,7 @@ gsf_input_memory_new (guint8 const *buf, gsf_off_t length, gboolean needs_free)
 
 /**
  * gsf_input_memory_new_clone:
- * @buf: The input bytes
+ * @buf: (array length=length): The input bytes
  * @length: The length of @buf
  *
  * Returns: A new #GsfInputMemory
@@ -192,7 +192,7 @@ GSF_CLASS (GsfInputMemory, gsf_input_memory,
 /**
  * gsf_input_mmap_new:
  * @filename: The file on disk that you want to mmap
- * @err: A #GError, or optionally %NULL
+ * @err: (nullable): A #GError
  *
  * Returns: A new #GsfInputMemory
  */
diff --git a/gsf/gsf-input-textline.c b/gsf/gsf-input-textline.c
index 6c84a75..97b4b31 100644
--- a/gsf/gsf-input-textline.c
+++ b/gsf/gsf-input-textline.c
@@ -51,7 +51,7 @@ typedef struct {
  *
  * <note>This adds a reference to @source.</note>
  *
- * Returns: a new file or %NULL.
+ * Returns: (nullable): a new file
  **/
 GsfInput *
 gsf_input_textline_new (GsfInput *source)
@@ -163,7 +163,7 @@ GSF_CLASS (GsfInputTextline, gsf_input_textline,
  * Trailing newlines and carriage returns are stripped, and the resultant buffer
  * can be edited.
  *
- * Returns: (transfer none): the string read, or %NULL on eof.
+ * Returns: (array) (transfer none) (nullable): the string read, or %NULL on eof.
  **/
 unsigned char *
 gsf_input_textline_ascii_gets (GsfInputTextline *textline)
@@ -179,7 +179,7 @@ gsf_input_textline_ascii_gets (GsfInputTextline *textline)
  * Trailing newlines and carriage returns are stripped, and the resultant buffer
  * can be edited.
  *
- * Returns: (transfer none): the string read, or %NULL on eof.
+ * Returns: (array) (transfer none) (nullable): the string read, or %NULL on eof.
  **/
 guint8 *
 gsf_input_textline_utf8_gets (GsfInputTextline *textline)
diff --git a/gsf/gsf-input.c b/gsf/gsf-input.c
index 14de590..aabf8a5 100644
--- a/gsf/gsf-input.c
+++ b/gsf/gsf-input.c
@@ -249,7 +249,7 @@ gsf_input_name (GsfInput *input)
  * gsf_input_container:
  * @input: the input stream
  *
- * Returns: (transfer none): @input's container, potentially %NULL.
+ * Returns: (transfer none) (nullable): @input's container
  **/
 GsfInfile *
 gsf_input_container (GsfInput *input)
@@ -259,13 +259,13 @@ gsf_input_container (GsfInput *input)
 }
 
 /**
- * gsf_input_dup:
+ * gsf_input_dup: (virtual Dup):
  * @input: The input to duplicate
  * @err: (allow-none): place to store a #GError if anything goes wrong
  *
  * Duplicates input @src leaving the new one at the same offset.
  *
- * Returns: (transfer full): the duplicate, or %NULL on error
+ * Returns: (transfer full) (nullable): the duplicate
  **/
 GsfInput *
 gsf_input_dup (GsfInput *input, GError **err)
@@ -298,7 +298,7 @@ gsf_input_dup (GsfInput *input, GError **err)
 }
 
 /**
- * gsf_input_sibling:
+ * gsf_input_sibling: (virtual OpenSibling)
  * @input: The input
  * @name: name.
  * @err: (allow-none): place to store a #GError if anything goes wrong
@@ -310,7 +310,7 @@ gsf_input_dup (GsfInput *input, GError **err)
  * Attempts to open a 'sibling' of @input.  The caller is responsible for
  * managing the resulting object.
  *
- * Returns: (transfer full): A related #GsfInput or %NULL on failure.
+ * Returns: (transfer full): A related #GsfInput
  **/
 GsfInput *
 gsf_input_sibling (GsfInput const *input, char const *name, GError **err)
@@ -350,17 +350,17 @@ gsf_input_eof (GsfInput *input)
 }
 
 /**
- * gsf_input_read: (skip)
+ * gsf_input_read: (virtual Read) (skip)
  * @input: the input stream
  * @num_bytes: number of bytes to read
- * @optional_buffer: Pointer to destination memory area
+ * @optional_buffer: (array) (allow-none): Pointer to destination memory area
  *
  * Read at least @num_bytes.  Does not change the current position if there
  * is an error.  Will only read if the entire amount can be read.  Invalidates
  * the buffer associated with previous calls to gsf_input_read.
  *
- * Returns: pointer to the buffer or %NULL if there is an error or 0
- * bytes are requested.
+ * Returns: (array) (nullable): pointer to the buffer or %NULL if there is
+ * an error or 0 bytes are requested.
  **/
 
 guint8 const *
@@ -444,7 +444,7 @@ gsf_input_tell (GsfInput *input)
 }
 
 /**
- * gsf_input_seek:
+ * gsf_input_seek: (virtual Seek)
  * @input: the input stream
  * @offset: target offset
  * @whence: determines whether the offset is relative to the beginning or
@@ -488,7 +488,7 @@ gsf_input_seek (GsfInput *input, gsf_off_t offset, GSeekType whence)
 /**
  * gsf_input_set_name:
  * @input: the input stream
- * @name: the new name of the stream, or %NULL.
+ * @name: (allow-none): the new name of the stream
  *
  * protected.
  *
@@ -531,7 +531,7 @@ gsf_input_set_name_from_filename (GsfInput *input, char const *filename)
 /**
  * gsf_input_set_container:
  * @input: the input stream
- * @container:
+ * @container: (allow-none)
  *
  * Returns: %TRUE if the assignment was ok.
  */
diff --git a/gsf/gsf-libxml.c b/gsf/gsf-libxml.c
index fc77c47..29bfa6d 100644
--- a/gsf/gsf-libxml.c
+++ b/gsf/gsf-libxml.c
@@ -352,7 +352,7 @@ gsf_xml_parser_context_full (GsfInput *input, xmlSAXHandlerPtr sax, gpointer use
  *
  * NOTE: skipped since xmlParserCtxt is not exported to introspection.
  *
- * Returns: A parser context or %NULL
+ * Returns: (nullable): A parser context
  **/
 xmlParserCtxtPtr
 gsf_xml_parser_context (GsfInput *input)
@@ -1117,14 +1117,14 @@ gsf_xml_in_doc_free (GsfXMLInDoc *doc)
 
 /**
  * gsf_xml_in_doc_new:
- * @nodes: an array of node descriptors
- * @ns: an array of namespace identifiers
+ * @nodes: (array zero-terminated=1): an array of node descriptors
+ * @ns: (array zero-terminated=1): an array of namespace identifiers
  *
  * Combine the nodes in the %NULL terminated array starting at @nodes with the
  * name spaces in the %NULL terminated array starting at @ns.  Prepare the
  * data structures necessary to validate a doument based on that description.
  *
- * Returns: %NULL on error
+ * Returns: (nullable): a #GsfXMLInDoc
  **/
 GsfXMLInDoc *
 gsf_xml_in_doc_new (GsfXMLInNode const *nodes, GsfXMLInNS const *ns)
@@ -1173,7 +1173,7 @@ gsf_xml_in_doc_get_type (void)
 /**
  * gsf_xml_in_doc_add_nodes:
  * @doc: #GsfXMLInDoc
- * @nodes: %NULL terminated array of #GsfXMLInNode
+ * @nodes: (array zero-terminated=1): %NULL terminated array of #GsfXMLInNode
  *
  * Adds additional nodes to the structure of @doc
  **/
@@ -1279,7 +1279,7 @@ gsf_xml_in_doc_set_unknown_handler (GsfXMLInDoc *doc,
  * @doc: #GsfXMLInDoc
  * @new_state: arbitrary content for the parser
  * @dtor: (scope call): #GsfXMLInExtDtor
- * @attrs: array of xmlChar const *
+ * @attrs: (array) (element-type utf8): array of xmlChar const *
  *
  * Take the first node from @doc as the current node and call its start handler.
  **/
@@ -1408,8 +1408,8 @@ gsf_xml_in_set_silent_unknowns (GsfXMLIn *xin, gboolean silent)
  *
  * According to @state is @str in the namespace @ns_id ?
  *
- * Returns: (transfer none): a pointer to @str after the namespace if
- * successful, otherwise %NULL.
+ * Returns: (transfer none) (nullable): 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)
@@ -1833,7 +1833,7 @@ close_tag_if_neccessary (GsfXMLOut* xout)
 /**
  * gsf_xml_out_add_cstr_unchecked:
  * @xout: #GsfXMLOut
- * @id: (allow-none): tag id or %NULL for content
+ * @id: (allow-none): tag id, or %NULL for node content
  * @val_utf8: (allow-none): a utf8 encoded string to export
  *
  * dump @val_utf8 to an attribute named @id without checking to see if
@@ -1860,7 +1860,7 @@ gsf_xml_out_add_cstr_unchecked (GsfXMLOut *xout, char const *id,
 /**
  * gsf_xml_out_add_cstr:
  * @xout: #GsfXMLOut
- * @id: (allow-none): tag id or %NULL for content
+ * @id: (allow-none): tag id, or %NULL for node content
  * @val_utf8: (allow-none): a utf8 encoded string
  *
  * dump @val_utf8 to an attribute named @id or as the nodes content escaping
@@ -1939,7 +1939,7 @@ gsf_xml_out_add_cstr (GsfXMLOut *xout, char const *id,
 /**
  * gsf_xml_out_add_bool:
  * @xout: #GsfXMLOut
- * @id: (allow-none): tag id or %NULL for content
+ * @id: (allow-none): tag id, or %NULL for node content
  * @val: a boolean
  *
  * dump boolean value @val to an attribute named @id or as the nodes content
@@ -1956,7 +1956,7 @@ gsf_xml_out_add_bool (GsfXMLOut *xout, char const *id,
 /**
  * gsf_xml_out_add_int:
  * @xout: #GsfXMLOut
- * @id: (allow-none): tag id or %NULL for content
+ * @id: (allow-none): tag id, or %NULL for node content
  * @val: the value
  *
  * dump integer value @val to an attribute named @id or as the nodes content
@@ -1973,7 +1973,7 @@ gsf_xml_out_add_int (GsfXMLOut *xout, char const *id,
 /**
  * gsf_xml_out_add_uint:
  * @xout: #GsfXMLOut
- * @id: (allow-none): tag id or %NULL for content
+ * @id: (allow-none): tag id, or %NULL for node content
  * @val: the value
  *
  * dump unsigned integer value @val to an attribute named @id or as the nodes
@@ -1991,7 +1991,7 @@ gsf_xml_out_add_uint (GsfXMLOut *xout, char const *id,
 /**
  * gsf_xml_out_add_float:
  * @xout: #GsfXMLOut
- * @id: (allow-none): tag id or %NULL for content
+ * @id: (allow-none): tag id, or %NULL for node content
  * @val: the value
  * @precision: the number of significant digits to use, -1 meaning "enough".
  *
@@ -2018,7 +2018,7 @@ gsf_xml_out_add_float (GsfXMLOut *xout, char const *id,
 /**
  * gsf_xml_out_add_color:
  * @xout: #GsfXMLOut
- * @id: (allow-none): tag id or %NULL for content
+ * @id: (allow-none): tag id, or %NULL for node content
  * @r: Red value
  * @g: Green value
  * @b: Blue value
@@ -2037,7 +2037,7 @@ gsf_xml_out_add_color (GsfXMLOut *xout, char const *id,
 /**
  * gsf_xml_out_add_enum:
  * @xout: #GsfXMLOut
- * @id: (allow-none): tag id or %NULL for content
+ * @id: (allow-none): tag id, or %NULL for node content
  * @etype: #GType
  * @val: enum element number
  *
@@ -2060,7 +2060,7 @@ gsf_xml_out_add_enum (GsfXMLOut *xout, char const *id, GType etype, gint val)
 /**
  * gsf_xml_out_add_gvalue:
  * @xout: #GsfXMLOut
- * @id: (allow-none): tag id or %NULL for content
+ * @id: (allow-none): tag id, or %NULL for node content
  * @val: #GValue
  *
  * Output the value of @val as a string.  Does NOT store any type information
@@ -2141,8 +2141,8 @@ gsf_xml_out_add_gvalue (GsfXMLOut *xout, char const *id, GValue const *val)
 /**
  * gsf_xml_out_add_base64:
  * @xout: #GsfXMLOut
- * @id: (allow-none): tag id or %NULL for content
- * @data: Data to be written
+ * @id: (allow-none): tag id, or %NULL for node content
+ * @data: (array length=len): Data to be written
  * @len: Length of data
  *
  * Dump @len bytes in @data into the content of node @id using base64
@@ -2169,7 +2169,7 @@ gsf_xml_out_add_base64 (GsfXMLOut *xout, char const *id,
  *
  * Get the #GsfOutput we are writing to..
  *
- * Returns: (transfer none): #GsfInput or %NULL.
+ * Returns: (transfer none) (nullable): #GsfInput
  **/
 GsfOutput *
 gsf_xml_out_get_output (GsfXMLOut const *xout)
diff --git a/gsf/gsf-opendoc-utils.c b/gsf/gsf-opendoc-utils.c
index 97f30d1..e180134 100644
--- a/gsf/gsf-opendoc-utils.c
+++ b/gsf/gsf-opendoc-utils.c
@@ -756,7 +756,7 @@ meta_write_props (char const *prop_name, GsfDocProp *prop, GsfXMLOut *output)
 /**
  * gsf_doc_meta_data_write_to_odf:
  * @md: #GsfDocMetaData
- * @output: a pointer to a #GsfOutput.
+ * @output: (type GsfXMLOut): a pointer to a #GsfOutput.
  *
  * Since: 1.14.24
  *
diff --git a/gsf/gsf-outfile.c b/gsf/gsf-outfile.c
index 08ed232..12a5c2f 100644
--- a/gsf/gsf-outfile.c
+++ b/gsf/gsf-outfile.c
@@ -70,7 +70,7 @@ gsf_outfile_new_child_full (GsfOutfile *outfile,
 }
 
 /**
- * gsf_outfile_new_child_varg:
+ * gsf_outfile_new_child_varg: (virtual new_child)
  * @outfile: A #GsfOutfile
  * @name: The name of the new child to create
  * @is_dir: %TRUE to create a directory, %FALSE to create a plain file
diff --git a/gsf/gsf-output-memory.c b/gsf/gsf-output-memory.c
index 2f6e5c7..57ef07a 100644
--- a/gsf/gsf-output-memory.c
+++ b/gsf/gsf-output-memory.c
@@ -42,7 +42,7 @@ typedef struct {
 /**
  * gsf_output_memory_new:
  *
- * Returns: a new file or %NULL.
+ * Returns: (nullable): a new file.
  **/
 GsfOutput *
 gsf_output_memory_new (void)
@@ -188,7 +188,7 @@ gsf_output_memory_class_init (GObjectClass *gobject_class)
  * gsf_output_memory_get_bytes:
  * @mem: the output device.
  *
- * Returns: The data that has been written to @mem, or %NULL
+ * Returns: (array) (nullable): The data that has been written to @mem
  **/
 const guint8 *
 gsf_output_memory_get_bytes (GsfOutputMemory * mem)
diff --git a/gsf/gsf-output.c b/gsf/gsf-output.c
index 6d116c2..a5e50c7 100644
--- a/gsf/gsf-output.c
+++ b/gsf/gsf-output.c
@@ -261,7 +261,7 @@ GSF_CLASS_ABSTRACT (GsfOutput, gsf_output,
  *
  * Give the name of @output.
  *
- * Returns: (transfer none): @output's name in utf8 form.
+ * Returns: (transfer none) (nullable): @output's name in utf8 form.
  **/
 char const *
 gsf_output_name (GsfOutput const *output)
@@ -274,7 +274,7 @@ gsf_output_name (GsfOutput const *output)
  * gsf_output_container:
  * @output:
  *
- * Returns: (transfer none): @output's container, potentially %NULL.
+ * Returns: (transfer none) (nullable): @output's container
  **/
 GsfOutfile *
 gsf_output_container (GsfOutput const *output)
@@ -299,7 +299,7 @@ gsf_output_size (GsfOutput *output)
 }
 
 /**
- * gsf_output_close:
+ * gsf_output_close: (virtual Close)
  * @output: #GsfOutput
  *
  * Close a stream.
@@ -356,7 +356,7 @@ gsf_output_tell     (GsfOutput *output)
 }
 
 /**
- * gsf_output_seek:
+ * gsf_output_seek: (virtual Seek)
  * @output: #GsfOutput
  * @offset: Relative amount to reposition
  * @whence: What the offset is relative to.
@@ -423,7 +423,7 @@ gsf_output_inc_cur_offset (GsfOutput *output, gsf_off_t num_bytes)
 }
 
 /**
- * gsf_output_write:
+ * gsf_output_write: (virtual Write)
  * @output: Output stream
  * @num_bytes: Number of bytes to write
  * @data: (in) (array length=num_bytes): Data to write.
@@ -451,7 +451,7 @@ gsf_output_write (GsfOutput *output,
  * gsf_output_error:
  * @output:
  *
- * Returns: (transfer none): the last error logged on the output, or %NULL.
+ * Returns: (transfer none) (nullable): the last error logged on the output
  **/
 GError const *
 gsf_output_error (GsfOutput const *output)
@@ -625,8 +625,8 @@ gsf_output_unwrap (GObject *wrapper, GsfOutput *wrapee)
  * gsf_output_get_modtime:
  * @output: the output stream
  *
- * Returns: (transfer none): A #GDateTime representing when the output
- * was last modified, or %NULL if not known.
+ * Returns: (transfer none) (nullable): A #GDateTime representing when
+ * the output was last modified
  */
 GDateTime *
 gsf_output_get_modtime (GsfOutput *output)
@@ -694,7 +694,7 @@ gsf_output_printf (GsfOutput *output, char const *format, ...)
 }
 
 /**
- * gsf_output_vprintf:
+ * gsf_output_vprintf: (virtual Vprintf)
  * @output: A #GsfOutput
  * @format: The printf-style format string
  * @args: the arguments for @format
diff --git a/gsf/gsf-utils.c b/gsf/gsf-utils.c
index 69ee7af..063402a 100644
--- a/gsf/gsf-utils.c
+++ b/gsf/gsf-utils.c
@@ -600,12 +600,12 @@ gsf_filename_to_utf8 (char const *filename, gboolean quoted)
 
 /**
  * gsf_base64_encode_close:
- * @in: Data to be encoded
+ * @in: (array length=inlen): Data to be encoded
  * @inlen: Length of data to be encoded
  * @break_lines: Whether to use line breaks
- * @out: Encoded data.
- * @state: holds the number of bits that are stored in @save
- * @save: leftover bits that have not yet been decoded
+ * @out: (array): Encoded data.
+ * @state: (inout): holds the number of bits that are stored in @save
+ * @save: (inout): leftover bits that have not yet been decoded
  *
  * This funcion should be called to when finished encoding everything, to
  * flush off the last little bit.
@@ -626,12 +626,12 @@ gsf_base64_encode_close (guint8 const *in, size_t inlen,
 
 /**
  * gsf_base64_encode_step:
- * @in: input stream
+ * @in: (array): input stream
  * @len: max length of data to decode
  * @break_lines: Whether to use line breaks
- * @out: output stream
- * @state: holds the number of bits that are stored in @save
- * @save: leftover bits that have not yet been decoded
+ * @out: (array): output stream
+ * @state: (inout): holds the number of bits that are stored in @save
+ * @save: (inout): leftover bits that have not yet been decoded
  *
  * Performs an 'encode step', only encodes blocks of 3 characters from @in into
  * the output @out at a time, saves left-over state in @state and @save
@@ -649,11 +649,11 @@ gsf_base64_encode_step (guint8 const *in, size_t len,
 
 /**
  * gsf_base64_decode_step:
- * @in: input stream
+ * @in: (array): input stream
  * @len: max length of data to decode
- * @out: output stream
- * @state: holds the number of bits that are stored in @save
- * @save: leftover bits that have not yet been decoded
+ * @out: (array): output stream
+ * @state: (inout): holds the number of bits that are stored in @save
+ * @save: (inout): leftover bits that have not yet been decoded
  *
  * Decodes a chunk of base64 encoded data
  *
@@ -668,7 +668,7 @@ gsf_base64_decode_step (guint8 const *in, size_t len, guint8 *out,
 
 /**
  * gsf_base64_encode_simple:
- * @data: data stream
+ * @data: (array): data stream
  * @len: max length of data to encode
  *
  * Encodes data from @data back into @data using base64 encoding.
@@ -695,7 +695,7 @@ gsf_base64_encode_simple (guint8 const *data, size_t len)
 
 /**
  * gsf_base64_decode_simple:
- * @data: data stream
+ * @data: (array): data stream
  * @len: max length of data to decode
  *
  * Decodes a chunk of base64 encoded data from @data back into @data.
@@ -797,6 +797,12 @@ gsf_property_settings_collect (GType object_type,
   va_end (var_args);
 }
 
+/**
+ * gsf_property_settings_find:
+ * @name:
+ * @params: (array length=n_params):
+ * @n_params:
+ */
 const GParameter *
 gsf_property_settings_find (const char *name,
                            const GParameter *params,
@@ -811,6 +817,11 @@ gsf_property_settings_find (const char *name,
        return NULL;
 }
 
+/**
+ * gsf_property_settings_free:
+ * @params: (array length=n_params) (transfer full):
+ * @n_params:
+ */
 void
 gsf_property_settings_free (GParameter *params,
                            size_t n_params)
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]