[gnumeric] Introspection fixes

[Morten Welinder <mortenw src gnome org>]

commit e73da76ebe21114b21b74b225750316a7417dee5
Author: Morten Welinder <terra gnome org>
Date:   Tue May 8 13:40:05 2018 -0400

    Introspection fixes

 NEWS                 |    1 +
 src/gnm-random.c     |    7 +++++--
 src/gutils.c         |   22 ++++++++++++++++++----
 src/hlink.c          |   32 +++++++++++++++++++++++++++-----
 src/input-msg.c      |   24 ++++++++++++++++++------
 src/pattern.c        |    2 +-
 src/session.c        |    4 ++++
 src/sheet-autofill.c |    9 +++++++--
 src/sheet-filter.c   |   39 ++++++++++++++++++++++++++-------------
 src/stf.c            |   10 ++++++++--
 10 files changed, 115 insertions(+), 35 deletions(-)
---
diff --git a/NEWS b/NEWS
index b794986..5f49d78 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,7 @@ Gnumeric 1.12.42
 
 Morten:
        * Plug leaks.
+       * Introspection fixes.
 
 --------------------------------------------------------------------------
 Gnumeric 1.12.41
diff --git a/src/gnm-random.c b/src/gnm-random.c
index e0a239b..d56e329 100644
--- a/src/gnm-random.c
+++ b/src/gnm-random.c
@@ -409,8 +409,11 @@ random_01 (void)
 }
 
 /* ------------------------------------------------------------------------ */
-/*
- * Generate a N(0,1) distributed number.
+
+/**
+ * random_normal:
+ *
+ * Returns: a N(0,1) distributed random number.
  */
 gnm_float
 random_normal (void)
diff --git a/src/gutils.c b/src/gutils.c
index b7cf2ba..75c47a4 100644
--- a/src/gutils.c
+++ b/src/gutils.c
@@ -708,6 +708,13 @@ gnm_insert_meta_date (GODoc *doc, char const *name)
 
 /* ------------------------------------------------------------------------- */
 
+/**
+ * gnm_object_get_bool:
+ * @o: #GObject
+ * @name: property name
+ *
+ * Returns: the value of @o's boolean property @name.
+ */
 gboolean
 gnm_object_get_bool (gpointer o, const char *name)
 {
@@ -716,6 +723,16 @@ gnm_object_get_bool (gpointer o, const char *name)
        return b;
 }
 
+/**
+ * gnm_object_has_readable_prop:
+ * @obj: #GObject
+ * @property: property name
+ * @typ: property's type or %G_TYPE_NONE.  (Exact type, not is-a.)
+ * @pres: (out) (optional): location to store property value.
+ *
+ * Returns: %TRUE if @obj has a readable property named @property
+ * of type @typ.
+ */
 gboolean
 gnm_object_has_readable_prop (gconstpointer obj, const char *property,
                              GType typ, gpointer pres)
@@ -738,8 +755,7 @@ gnm_object_has_readable_prop (gconstpointer obj, const char *property,
        return TRUE;
 }
 
-
-
+/* ------------------------------------------------------------------------- */
 
 gint
 gnm_float_equal (gnm_float const *a, const gnm_float *b)
@@ -747,8 +763,6 @@ gnm_float_equal (gnm_float const *a, const gnm_float *b)
        return (*a == *b);
 }
 
-/* ------------------------------------------------------------------------- */
-
 guint
 gnm_float_hash (gnm_float const *d)
 {
diff --git a/src/hlink.c b/src/hlink.c
index d67c6ea..ed7b3c9 100644
--- a/src/hlink.c
+++ b/src/hlink.c
@@ -53,10 +53,10 @@ static GObjectClass *gnm_hlink_parent_class;
  */
 /**
  * gnm_hlink_activate:
- * @lnk:
+ * @lnk: #GnmHLink
  * @wbcg: the wbcg that activated the link
  *
- * Returns: TRUE if the link successfully activated.
+ * Returns: %TRUE if the link successfully activated.
  **/
 gboolean
 gnm_hlink_activate (GnmHLink *lnk, WBCGtk *wbcg)
@@ -71,7 +71,7 @@ gnm_hlink_activate (GnmHLink *lnk, WBCGtk *wbcg)
  * @sheet: #Sheet
  * @pos: #GcmCellPos
  *
- * Returns: (transfer none): the found #GnmHLink.
+ * Returns: (transfer none) (nullable): the found #GnmHLink.
  **/
 GnmHLink *
 gnm_sheet_hlink_find (Sheet const *sheet, GnmCellPos const *pos)
@@ -138,6 +138,12 @@ gnm_hlink_init (GObject *obj)
 GSF_CLASS_ABSTRACT (GnmHLink, gnm_hlink,
                    gnm_hlink_class_init, gnm_hlink_init, G_TYPE_OBJECT)
 
+/**
+ * gnm_hlink_get_target:
+ * @lnk: #GnmHLink
+ *
+ * Returns: (transfer none): @lnk's target.
+ */
 const char *
 gnm_hlink_get_target (GnmHLink const *lnk)
 {
@@ -154,6 +160,12 @@ gnm_hlink_set_target (GnmHLink *lnk, gchar const *target)
        GET_CLASS (lnk)->set_target (lnk, target);
 }
 
+/**
+ * gnm_hlink_get_tip:
+ * @lnk: #GnmHLink
+ *
+ * Returns: (transfer none): @lnk's tooltip.
+ */
 const char *
 gnm_hlink_get_tip (GnmHLink const *lnk)
 {
@@ -175,7 +187,7 @@ gnm_hlink_set_tip (GnmHLink *lnk, gchar const *tip)
 
 /**
  * gnm_hlink_get_sheet:
- * @lnk: link
+ * @lnk: #GnmHLink
  *
  * Returns: (transfer none): the sheet
  */
@@ -400,7 +412,7 @@ GSF_CLASS (GnmHLinkCurWB, gnm_hlink_cur_wb,
 /**
  * gnm_hlink_get_range_target:
  * @lnk: the hyperlink to query
- * @sr: location to start link target range
+ * @sr: (out): location to store link target range
  *
  * This function determines the location that a link points to.  It will
  * resolve names.
@@ -417,6 +429,8 @@ gnm_hlink_get_range_target (GnmHLink const *lnk, GnmSheetRange *sr)
        GnmParsePos pp;
        Sheet *start_sheet, *end_sheet;
 
+       memset (sr, 0, sizeof (*sr));
+
        g_return_val_if_fail (GNM_IS_HLINK (lnk), FALSE);
 
        if (!GNM_IS_HLINK_CUR_WB (lnk))
@@ -441,6 +455,14 @@ gnm_hlink_get_range_target (GnmHLink const *lnk, GnmSheetRange *sr)
 }
 
 
+/**
+ * gnm_hlink_get_target_expr:
+ * @lnk: the hyperlink to query
+ *
+ * This function determines the location that a link points to.
+ *
+ * Returns: (transfer none) (nullable): A #GnmExprTop describing the target.
+ */
 GnmExprTop const *
 gnm_hlink_get_target_expr (GnmHLink const *lnk)
 {
diff --git a/src/input-msg.c b/src/input-msg.c
index ce074d3..d182dc8 100644
--- a/src/input-msg.c
+++ b/src/input-msg.c
@@ -74,8 +74,8 @@ GSF_CLASS (GnmInputMsg, gnm_input_msg,
 
 /**
  * gnm_input_msg_new:
- * @msg:
- * @title:
+ * @msg: (nullable): A message to show
+ * @title: (nullable): A title to show for the message
  *
  * Returns: a ref to new #GnmInputMsg.
  **/
@@ -106,14 +106,26 @@ gnm_input_msg_equal (GnmInputMsg const *a,
 }
 
 
+/**
+ * gnm_input_msg_get_msg:
+ * @msg: #GnmInputMsg
+ *
+ * Returns: (transfer none): The message to show
+ **/
 char const *
-gnm_input_msg_get_msg (GnmInputMsg const *imsg)
+gnm_input_msg_get_msg (GnmInputMsg const *msg)
 {
-       return (imsg->msg != NULL) ? imsg->msg->str : "";
+       return (msg->msg != NULL) ? msg->msg->str : "";
 }
 
+/**
+ * gnm_input_msg_get_title:
+ * @msg: #GnmInputMsg
+ *
+ * Returns: (transfer none): The title of the message to show
+ **/
 char const  *
-gnm_input_msg_get_title (GnmInputMsg const *imsg)
+gnm_input_msg_get_title (GnmInputMsg const *msg)
 {
-       return (imsg->title != NULL) ? imsg->title->str : "";
+       return (msg->title != NULL) ? msg->title->str : "";
 }
diff --git a/src/pattern.c b/src/pattern.c
index 14aefd5..d6cbe0f 100644
--- a/src/pattern.c
+++ b/src/pattern.c
@@ -57,7 +57,7 @@ static const GOPatternType patterns[] = {
 
 gboolean
 gnm_pattern_background_set (GnmStyle const *mstyle, cairo_t *cr,
-                        gboolean const is_selected, GtkStyleContext *ctxt)
+                           gboolean const is_selected, GtkStyleContext *ctxt)
 {
        int pattern;
 
diff --git a/src/session.c b/src/session.c
index ff15434..1d0cb27 100644
--- a/src/session.c
+++ b/src/session.c
@@ -20,6 +20,10 @@
 #include <gnumeric-config.h>
 
 #include "session.h"
+
+/**
+ * gnm_session_init: (skip)
+ */
 void
 gnm_session_init (char const *argv0)
 {
diff --git a/src/sheet-autofill.c b/src/sheet-autofill.c
index d72e7e2..494cd1a 100644
--- a/src/sheet-autofill.c
+++ b/src/sheet-autofill.c
@@ -38,6 +38,9 @@ static char *weekday_names_short[7 + 1];
 static char *quarters[4 + 1];
 static gboolean has_quarters;
 
+/**
+ * gnm_autofill_init: (skip)
+ */
 void
 gnm_autofill_init (void)
 {
@@ -67,6 +70,9 @@ gnm_autofill_init (void)
        }
 }
 
+/**
+ * gnm_autofill_shutdown: (skip)
+ */
 void
 gnm_autofill_shutdown (void)
 {
@@ -259,8 +265,7 @@ as_finalize (ArithString *as)
                g_string_free (as->suffix, TRUE);
 }
 
-static
-gboolean
+static gboolean
 as_check_prefix_suffix (ArithString *as, char const *s, gsize slen)
 {
        if (as->prefix) {
diff --git a/src/sheet-filter.c b/src/sheet-filter.c
index 4466664..71d8fca 100644
--- a/src/sheet-filter.c
+++ b/src/sheet-filter.c
@@ -803,9 +803,10 @@ gnm_filter_remove (GnmFilter *filter)
 
 /**
  * gnm_filter_get_condition:
- * @filter:
- * @i:
+ * @filter: #GnmFilter
+ * @i: zero-based index
  *
+ * Returns: (transfer none): the @i'th condition of @filter
  **/
 GnmFilterCondition const *
 gnm_filter_get_condition (GnmFilter const *filter, unsigned i)
@@ -819,6 +820,12 @@ gnm_filter_get_condition (GnmFilter const *filter, unsigned i)
        return fcombo->cond;
 }
 
+/**
+ * gnm_filter_reapply:
+ * @filter: #GnmFilter
+ *
+ * Reapplies @filter after changes.
+ **/
 void
 gnm_filter_reapply (GnmFilter *filter)
 {
@@ -864,7 +871,7 @@ gnm_filter_update_active (GnmFilter *filter)
  * @apply:
  *
  * Change the @i-th condition of @filter to @cond.  If @apply is
- * TRUE @filter is used to set the visibility of the rows in @filter::sheet
+ * %TRUE, @filter is used to set the visibility of the rows in @filter::sheet
  *
  * Absorbs the reference to @cond.
  **/
@@ -926,8 +933,9 @@ gnm_filter_overlaps_range (GnmFilter const *filter, GnmRange const *r)
 /**
  * gnm_sheet_filter_at_pos:
  * @sheet: #Sheet
+ * @pos: location to query
  *
- * Returns : #GnmRange
+ * Returns: (transfer none) (nullable): #GnmFilter covering @pos.
  **/
 GnmFilter *
 gnm_sheet_filter_at_pos (Sheet const *sheet, GnmCellPos const *pos)
@@ -948,11 +956,12 @@ gnm_sheet_filter_at_pos (Sheet const *sheet, GnmCellPos const *pos)
 
 /**
  * gnm_sheet_filter_intersect_rows:
- * @sheet:
+ * @sheet: #Sheet
  * @from: starting row number
  * @to: ending row number
  *
- * Returns: the filter, if any, that intersect the rows @from to @to
+ * Returns: (transfer none) (nullable): the #GnmFilter, if any, that
+ * intersects the rows @from to @to.
  **/
 GnmFilter *
 gnm_sheet_filter_intersect_rows (Sheet const *sheet, int from, int to)
@@ -970,6 +979,11 @@ gnm_sheet_filter_intersect_rows (Sheet const *sheet, int from, int to)
        return NULL;
 }
 
+/**
+ * gnm_sheet_filter_can_be_extended:
+ *
+ * Returns: (transfer full): #GnmRange
+ */
 GnmRange *
 gnm_sheet_filter_can_be_extended (G_GNUC_UNUSED Sheet const *sheet,
                                  GnmFilter const *f, GnmRange const *r)
@@ -1048,12 +1062,12 @@ gnm_filter_set_range (GnmFilter *filter, GnmRange *r)
 
 /**
  * gnm_sheet_filter_insdel_colrow:
- * @sheet:
- * @is_cols:
- * @is_insert:
- * @start:
- * @count:
- * @pundo: location to store undo closures.
+ * @sheet: #Sheet
+ * @is_cols: %TRUE for columns, %FALSE for rows.
+ * @is_insert: %TRUE for insert, %FALSE for delete.
+ * @start: Starting column or row.
+ * @count: Number of columns or rows.
+ * @pundo: (out) (optional): location to store undo closures.
  *
  * Adjust filters as necessary to handle col/row insertions and deletions
  **/
@@ -1194,4 +1208,3 @@ gnm_sheet_filter_insdel_colrow (Sheet *sheet,
 
        g_slist_free (filters);
 }
-
diff --git a/src/stf.c b/src/stf.c
index 189c141..4000b98 100644
--- a/src/stf.c
+++ b/src/stf.c
@@ -360,9 +360,9 @@ clear_stray_NULs (GOIOContext *context, GString *utf8data)
        if (null_chars > 0) {
                gchar const *format;
                gchar *msg;
-               format = ngettext ("The file contains %d NULL character. "
+               format = ngettext ("The file contains %d NUL character. "
                                   "It has been changed to a space.",
-                                  "The file contains %d NULL characters. "
+                                  "The file contains %d NUL characters. "
                                   "They have been changed to spaces.",
                                   null_chars);
                msg = g_strdup_printf (format, null_chars);
@@ -580,6 +580,9 @@ csv_tsv_probe (GOFileOpener const *fo, GsfInput *input, GOFileProbeLevel pl)
        }
 }
 
+/**
+ * stf_init: (skip)
+ */
 void
 stf_init (void)
 {
@@ -637,6 +640,9 @@ stf_init (void)
        g_object_unref (saver);
 }
 
+/**
+ * stf_shutdown: (skip)
+ */
 void
 stf_shutdown (void)
 {