[gnumeric] Introspection fixes

[Morten Welinder <mortenw src gnome org>]

commit da270082007f5aab51e95052e8c69a09afd67ce5
Author: Morten Welinder <terra gnome org>
Date:   Wed Apr 11 08:56:43 2018 -0400

    Introspection fixes

 src/format-template.c  |    2 +-
 src/ranges.c           |    3 +--
 src/sheet.c            |   32 +++++++++++++++++---------------
 src/tools/gnm-solver.c |    2 +-
 src/value.c            |    4 ++--
 src/workbook.c         |   12 ++++--------
 6 files changed, 26 insertions(+), 29 deletions(-)
---
diff --git a/src/format-template.c b/src/format-template.c
index acaa1cb..d44ad3f 100644
--- a/src/format-template.c
+++ b/src/format-template.c
@@ -519,7 +519,7 @@ GSF_XML_IN_NODE (START, TEMPLATE, GMR, "FormatTemplate", GSF_XML_NO_CONTENT, NUL
  * Create a new GnmFT and load a template file
  * into it.
  *
- * Return value: (transfer full): a new GnmFT (or NULL on error)
+ * Return value: (transfer full): a new GnmFT (or %NULL on error)
  **/
 GnmFT *
 gnm_ft_new_from_file (char const *filename, GOCmdContext *cc)
diff --git a/src/ranges.c b/src/ranges.c
index c362fbc..d15748b 100644
--- a/src/ranges.c
+++ b/src/ranges.c
@@ -1042,8 +1042,7 @@ undo_range_list_name (Sheet const *sheet, GSList const *ranges)
  * Parses a list of ranges, relative to the @sheet and returns a list with the
  * results.
  *
- * Returns: (element-type GnmValue) (transfer full): a GSList containing
- * Values of type VALUE_CELLRANGE, or NULL on failure
+ * Returns: (element-type GnmValue) (transfer full): a #GSList of #GnmValue.
  **/
 GSList *
 global_range_list_parse (Sheet *sheet, char const *str)
diff --git a/src/sheet.c b/src/sheet.c
index 14b5f7a..d9f9f27 100644
--- a/src/sheet.c
+++ b/src/sheet.c
@@ -2051,8 +2051,7 @@ sheet_update (Sheet const *sheet)
  * @col:    the cell column
  * @row:    the cell row
  *
- * Return value: a (GnmCell *) containing the GnmCell, or NULL if
- * the cell does not exist
+ * Return value: (nullable): a #GnmCell, or %NULL if the cell does not exist
  **/
 GnmCell *
 sheet_cell_get (Sheet const *sheet, int col, int row)
@@ -3729,42 +3728,45 @@ sheet_colrow_optimize (Sheet *sheet)
 
 /**
  * sheet_col_get:
+ * @col: column number
  *
- * Returns: (transfer none): an allocated column:  either an existing one,
- * or NULL
+ * Returns: (transfer none) (nullable): A #ColRowInfo for the column, or %NULL
+ * if none has been allocated yet.
  */
 ColRowInfo *
-sheet_col_get (Sheet const *sheet, int pos)
+sheet_col_get (Sheet const *sheet, int col)
 {
        ColRowSegment *segment;
 
        g_return_val_if_fail (IS_SHEET (sheet), NULL);
-       g_return_val_if_fail (pos < gnm_sheet_get_max_cols (sheet), NULL);
-       g_return_val_if_fail (pos >= 0, NULL);
+       g_return_val_if_fail (col < gnm_sheet_get_max_cols (sheet), NULL);
+       g_return_val_if_fail (col >= 0, NULL);
 
-       segment = COLROW_GET_SEGMENT (&(sheet->cols), pos);
+       segment = COLROW_GET_SEGMENT (&(sheet->cols), col);
        if (segment != NULL)
-               return segment->info[COLROW_SUB_INDEX (pos)];
+               return segment->info[COLROW_SUB_INDEX (col)];
        return NULL;
 }
 
 /**
  * sheet_row_get:
+ * @row: row number
  *
- * Returns an allocated row:  either an existing one, or NULL
+ * Returns: (transfer none) (nullable): A #ColRowInfo for the row, or %NULL
+ * if none has been allocated yet.
  */
 ColRowInfo *
-sheet_row_get (Sheet const *sheet, int pos)
+sheet_row_get (Sheet const *sheet, int row)
 {
        ColRowSegment *segment;
 
        g_return_val_if_fail (IS_SHEET (sheet), NULL);
-       g_return_val_if_fail (pos < gnm_sheet_get_max_rows (sheet), NULL);
-       g_return_val_if_fail (pos >= 0, NULL);
+       g_return_val_if_fail (row < gnm_sheet_get_max_rows (sheet), NULL);
+       g_return_val_if_fail (row >= 0, NULL);
 
-       segment = COLROW_GET_SEGMENT (&(sheet->rows), pos);
+       segment = COLROW_GET_SEGMENT (&(sheet->rows), row);
        if (segment != NULL)
-               return segment->info[COLROW_SUB_INDEX (pos)];
+               return segment->info[COLROW_SUB_INDEX (row)];
        return NULL;
 }
 
diff --git a/src/tools/gnm-solver.c b/src/tools/gnm-solver.c
index 88a809e..f026eda 100644
--- a/src/tools/gnm-solver.c
+++ b/src/tools/gnm-solver.c
@@ -2413,7 +2413,7 @@ gnm_solver_pick_lp_coords (GnmSolver *sol,
  * @x2: second coordinate value
  * @err: error location
  *
- * Returns: (transfer full): coordinates, or NULL in case of error.
+ * Returns: (transfer full) (nullable): coordinates, or %NULL in case of error.
  * Note: this function is not affected by the flip-sign property, even
  * if @ycell happens to coindice with the solver target cell.
  */
diff --git a/src/value.c b/src/value.c
index 30e1993..a24a7ac 100644
--- a/src/value.c
+++ b/src/value.c
@@ -367,7 +367,7 @@ value_new_cellrange_r (Sheet *sheet, GnmRange const *r)
  *
  * Parse @str using the convention associated with @sheet.
  * Returns a (GnmValue *) of type VALUE_CELLRANGE if the @range was
- * succesfully parsed or NULL on failure.
+ * succesfully parsed or %NULL on failure.
  */
 GnmValue *
 value_new_cellrange_str (Sheet *sheet, char const *str)
@@ -391,7 +391,7 @@ value_new_cellrange_str (Sheet *sheet, char const *str)
  *
  * Parse @str using the convention associated with @sheet.
  * Returns a (GnmValue *) of type VALUE_CELLRANGE if the @range was
- * succesfully parsed or NULL on failure.
+ * succesfully parsed or %NULL on failure.
  */
 GnmValue *
 value_new_cellrange_parsepos_str (GnmParsePos const *pp, char const *str,
diff --git a/src/workbook.c b/src/workbook.c
index 2de39b4..f7838d5 100644
--- a/src/workbook.c
+++ b/src/workbook.c
@@ -863,19 +863,16 @@ workbook_sheet_index_update (Workbook *wb, int start)
  * @wb: workbook to lookup the sheet on
  * @i: the sheet index we are looking for.
  *
- * Return value: (transfer none): a pointer to a Sheet or NULL if the sheet
- * was not found.
+ * Return value: (transfer none) (nullable): a pointer to a #Sheet
  */
 Sheet *
 workbook_sheet_by_index (Workbook const *wb, int i)
 {
        g_return_val_if_fail (GNM_IS_WORKBOOK (wb), NULL);
-       g_return_val_if_fail (i < (int)wb->sheets->len, NULL);
        g_return_val_if_fail (i >= -1, NULL);
 
-       /* i = -1 is special, return NULL */
-
-       if (i == -1)
+       // i = -1 is special, return NULL
+       if (i == -1 || i >= (int)wb->sheets->len)
                return NULL;
 
        return g_ptr_array_index (wb->sheets, i);
@@ -886,8 +883,7 @@ workbook_sheet_by_index (Workbook const *wb, int i)
  * @wb: workbook to lookup the sheet on
  * @sheet_name: the sheet name we are looking for.
  *
- * Return value: (transfer none): a pointer to a Sheet or NULL if the sheet
- * was not found.
+ * Return value: (transfer none) (nullable): a pointer to a #Sheet
  */
 Sheet *
 workbook_sheet_by_name (Workbook const *wb, char const *name)