From 850dbf260e62324d160ac24837e87f05d3265ae5 Mon Sep 17 00:00:00 2001
From: Morten Welinder <terra@gnome.org>
Date: Fri, 1 Jun 2018 14:59:19 -0400
Subject: [PATCH] Introspecion and doc fixes.

---
 plugins/openoffice/openoffice-read.c |   2 +-
 src/cell.c                           |   2 +-
 src/cellspan.c                       |   2 +-
 src/commands.c                       |  17 +++++-
 src/dependent.c                      |   4 +-
 src/dialogs/dialog-autoformat.c      |   2 +-
 src/dialogs/dialog-define-names.c    |   2 +-
 src/dialogs/dialog-solver.c          |   2 +-
 src/dialogs/dialog-stf-export.c      |   5 +-
 src/expr-name.c                      |   2 +-
 src/expr.c                           |   2 +-
 src/format-template.c                |   9 +--
 src/gnm-pane.c                       |   4 +-
 src/gui-util.c                       |   3 +-
 src/item-bar.c                       |   2 +-
 src/mstyle.c                         |   2 +-
 src/parse-util.c                     |   2 +-
 src/selection.c                      |   2 +-
 src/sheet-view.c                     |   2 +-
 src/sheet.c                          | 112 ++++++++++++++++++++---------------
 src/stf-export.c                     |   3 +-
 src/stf-parse.c                      |   4 +-
 src/style-conditions.c               |   2 +-
 src/tools/dao.c                      |   6 +-
 src/wbc-gtk.c                        |   2 +-
 src/widgets/gnm-expr-entry.c         |   9 +--
 26 files changed, 119 insertions(+), 87 deletions(-)

diff --git a/plugins/openoffice/openoffice-read.c b/plugins/openoffice/openoffice-read.c
index 3faf90ca7..2b50c0035 100644
--- a/plugins/openoffice/openoffice-read.c
+++ b/plugins/openoffice/openoffice-read.c
@@ -2107,7 +2107,7 @@ odf_fix_expr_names (OOParseState *state)
  * odf_expr_name_validate:
  * @name: tentative name
  *
- * returns TRUE if the given name is valid, FALSE otherwise.
+ * Returns: %TRUE if the given name is valid, %FALSE otherwise.
  *
  * We are accepting names here that contain periods or look like addresses.
  * They need to be replaced when we have finished parsing the file since
diff --git a/src/cell.c b/src/cell.c
index 35190fe33..0fc2feafd 100644
--- a/src/cell.c
+++ b/src/cell.c
@@ -262,7 +262,7 @@ gnm_cell_set_expr_unsafe (GnmCell *cell, GnmExprTop const *texpr)
 /**
  * gnm_cell_set_expr: (skip)
  * @cell: The #GnmCell
- * @texpr: The #GnmExprTop
+ * @texpr: (transfer none): The #GnmExprTop
  *
  * Stores and references the supplied expression
  *         marks the sheet as dirty.  Intented for use by import routines that
diff --git a/src/cellspan.c b/src/cellspan.c
index 29be1c89b..ea0020752 100644
--- a/src/cellspan.c
+++ b/src/cellspan.c
@@ -188,7 +188,7 @@ cell_span_info_get_type (void)
  *
  * We could probably have done the same thing with the span regions too, but
  * the current representation is not well suited to that type of search
- * returns TRUE if the cell is empty.
+ * returns %TRUE if the cell is empty.
  */
 static inline gboolean
 cellspan_is_empty (int col, GnmCell const *ok_span_cell)
diff --git a/src/commands.c b/src/commands.c
index c451487a6..bd7efde85 100644
--- a/src/commands.c
+++ b/src/commands.c
@@ -693,7 +693,22 @@ command_register_undo (WorkbookControl *wbc, GObject *obj)
  *  An internal utility to tack a new command
  *    onto the undo list.
  *
- * returns : TRUE if there was an error.
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
+ */
+
+
+/*
+ * cmd_set_text_full
+ *
+ * the caller is expected to have ensured:
+ *
+ * 1) that no array is being split
+ * 2) that the range is not locked.
+ *
+ * Note:
+ * We will free the selection but nothing else.
+ *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  */
 gboolean
 gnm_command_push_undo (WorkbookControl *wbc, GObject *obj)
diff --git a/src/dependent.c b/src/dependent.c
index 10d3d2a9c..217e6c08a 100644
--- a/src/dependent.c
+++ b/src/dependent.c
@@ -133,7 +133,7 @@ cset_insert (CSet **list, gpointer datum)
 		cs->data[cs->count++] = datum;
 }
 
-/* NOTE: takes reference.  Returns TRUE if datum was already present.  */
+/* NOTE: takes reference.  Returns %TRUE if datum was already present.  */
 static gboolean
 cset_insert_checked (CSet **list, gpointer datum)
 {
@@ -158,7 +158,7 @@ cset_insert_checked (CSet **list, gpointer datum)
 }
 
 
-/* NOTE: takes reference.  Returns TRUE if removed.  */
+/* NOTE: takes reference.  Returns %TRUE if removed.  */
 static gboolean
 cset_remove (CSet **list, gpointer datum)
 {
diff --git a/src/dialogs/dialog-autoformat.c b/src/dialogs/dialog-autoformat.c
index 0fc973cd7..08b5230fc 100644
--- a/src/dialogs/dialog-autoformat.c
+++ b/src/dialogs/dialog-autoformat.c
@@ -200,7 +200,7 @@ templates_free (AutoFormatState *state)
  * This function will load the templates in the currently selected
  * category group (it looks at state->category_groups to determine the selection)
  *
- * Return value: TRUE if all went well, FALSE otherwise.
+ * Returns: %TRUE if all went well, %FALSE otherwise.
  **/
 static gboolean
 templates_load (AutoFormatState *state)
diff --git a/src/dialogs/dialog-define-names.c b/src/dialogs/dialog-define-names.c
index 365a72c1e..320c014c2 100644
--- a/src/dialogs/dialog-define-names.c
+++ b/src/dialogs/dialog-define-names.c
@@ -162,7 +162,7 @@ name_guru_expand_at_iter (NameGuruState *state, GtkTreeIter *iter)
  * If the expresion that is about to be deleted is being used,
  * warn the user about it. Ask if we should proceed or not
  *
- * Return Value: TRUE if users confirms deletion, FALSE otherwise
+ * Returns: %TRUE if users confirms deletion, %FALSE otherwise
  **/
 
 static gboolean
diff --git a/src/dialogs/dialog-solver.c b/src/dialogs/dialog-solver.c
index f0894a392..b4d109af3 100644
--- a/src/dialogs/dialog-solver.c
+++ b/src/dialogs/dialog-solver.c
@@ -151,7 +151,7 @@ dialog_set_sec_button_sensitivity (G_GNUC_UNUSED GtkWidget *dummy,
 	gtk_widget_set_sensitive (GTK_WIDGET (state->rhs.entry), has_rhs);
 	gtk_widget_set_sensitive (GTK_WIDGET (state->rhs.label), has_rhs);
 
-	/* Return TRUE iff the current constraint is valid.  */
+	/* Return %TRUE iff the current constraint is valid.  */
 	return ready;
 }
 
diff --git a/src/dialogs/dialog-stf-export.c b/src/dialogs/dialog-stf-export.c
index d0053ceab..668f8639f 100644
--- a/src/dialogs/dialog-stf-export.c
+++ b/src/dialogs/dialog-stf-export.c
@@ -694,12 +694,13 @@ cb_next_page (TextExportState *state)
 
 /**
  * stf_export_dialog:
- * @wbcg: #WBCGtk (can be NULL)
+ * @wbcg: (nullable): #WBCGtk
  * @stfe: An exporter to set up (and take defaults from)
  * @wb: The #Workbook to export
  *
  * This will start the export assistant.
- * returns : TRUE if cancelled.
+ *
+ * Returns: %TRUE if cancelled.
  **/
 gboolean
 stf_export_dialog (WBCGtk *wbcg, GnmStfExport *stfe, Workbook *wb)
diff --git a/src/expr-name.c b/src/expr-name.c
index 245f1582f..d9a138dbd 100644
--- a/src/expr-name.c
+++ b/src/expr-name.c
@@ -1101,7 +1101,7 @@ expr_name_remove_dep (GnmNamedExpr *nexpr, GnmDependent *dep)
  * expr_name_is_placeholder:
  * @ne:
  *
- * Returns TRUE if @ne is a placeholder for an unknown name
+ * Returns: %TRUE if @ne is a placeholder for an unknown name
  **/
 gboolean
 expr_name_is_placeholder (GnmNamedExpr const *nexpr)
diff --git a/src/expr.c b/src/expr.c
index 183c21029..47abb3631 100644
--- a/src/expr.c
+++ b/src/expr.c
@@ -2141,7 +2141,7 @@ reloc_normalize_cellref (RelocInfoInternal const *rinfo, GnmCellRef const *ref,
 	}
 }
 
-/* Return TRUE if @pos is out of bounds */
+/* Return %TRUE if @pos is out of bounds */
 static gboolean
 reloc_restore_cellref (RelocInfoInternal const *rinfo,
 		       GnmSheetSize const *ss, GnmCellPos const *pos,
diff --git a/src/format-template.c b/src/format-template.c
index 7b3e88cfb..4fd2bec72 100644
--- a/src/format-template.c
+++ b/src/format-template.c
@@ -693,12 +693,12 @@ typedef void (* PCalcCallback) (GnmFT *ft, GnmRange *r, GnmStyle *mstyle, gpoint
  * format_template_range_check:
  * @ft: Format template
  * @r: Target range
- * @optional_cc: if non-NULL display an error message if @r is not
+ * @optional_cc: (nullable): if non-%NULL display an error message if @r is not
  *			appropriate for @ft.
  *
  * Check whether range @r is big enough to apply format template @ft to it.
  *
- * Return value: TRUE if @s is big enough, FALSE if not.
+ * Returns: %TRUE if @s is big enough, %FALSE if not.
  **/
 static gboolean
 format_template_range_check (GnmFT *ft, GnmRange const *r,
@@ -1040,10 +1040,11 @@ cb_format_sheet_style (GnmFT *ft, GnmRange *r, GnmStyle *mstyle, gpointer user)
  * gnm_ft_check_valid:
  * @ft:
  * @regions: (element-type GnmRange):
- * @cc: where to report errors
+ * @cc: (nullable): where to report errors
  *
  * check to see if the @regions are able to contain the support template @ft.
- * Returns TRUE if ok, else FALSE.  Will report an error to @cc if it is
+ *
+ * Returns: %TRUE if ok, else %FALSE.  Will report an error to @cc if it is
  * supplied.
  */
 gboolean
diff --git a/src/gnm-pane.c b/src/gnm-pane.c
index d3e9e8144..999ffa455 100644
--- a/src/gnm-pane.c
+++ b/src/gnm-pane.c
@@ -1369,7 +1369,7 @@ gnm_pane_find_row (GnmPane const *pane, gint64 y, gint64 *row_origin)
  *     recalculates the visible boundaries.
  *
  * @full_recompute:
- *       if TRUE recompute the pixel offsets of the top left row/col
+ *       if %TRUE recompute the pixel offsets of the top left row/col
  *       else assumes that the pixel offsets of the top left have not changed.
  */
 void
@@ -2138,7 +2138,7 @@ gnm_pane_size_guide_stop (GnmPane *pane)
 /**
  * gnm_pane_size_guide_motion:
  * @p: #GnmPane
- * @vert: TRUE for a vertical guide, FALSE for horizontal
+ * @vert: %TRUE for a vertical guide, %FALSE for horizontal
  * @guide_pos: in unscaled sheet pixel coords
  *
  * Moves the guide line to @guide_pos.
diff --git a/src/gui-util.c b/src/gui-util.c
index da70b87a2..4e7c4a4c5 100644
--- a/src/gui-util.c
+++ b/src/gui-util.c
@@ -339,7 +339,8 @@ gnm_keyed_dialog (WBCGtk *wbcg, GtkWindow *dialog, char const *key)
  * @key:     A key to identify the dialog
  *
  * Raise the dialog identified by key if it is registered on the wbcg.
- * Returns: (transfer none): TRUE if dialog found, FALSE if not.
+ *
+ * Returns: (transfer none) (type GtkDialog) (nullable): existing dialog
  **/
 gpointer
 gnm_dialog_raise_if_exists (WBCGtk *wbcg, char const *key)
diff --git a/src/item-bar.c b/src/item-bar.c
index 219855246..6b991904c 100644
--- a/src/item-bar.c
+++ b/src/item-bar.c
@@ -773,7 +773,7 @@ item_bar_distance (GocItem *item, double x, double y,
  * NOTE : this could easily be optimized.  We need not start at 0 every time.
  *        We could potentially use the routines in gnm-pane.
  *
- * Returns non-NULL if point (@x,@y) is on a division
+ * Returns non-%NULL if point (@x,@y) is on a division
  **/
 static ColRowInfo const *
 is_pointer_on_division (GnmItemBar const *ib, gint64 x, gint64 y,
diff --git a/src/mstyle.c b/src/mstyle.c
index d100e1603..a114c07a7 100644
--- a/src/mstyle.c
+++ b/src/mstyle.c
@@ -1292,7 +1292,7 @@ gnm_style_is_element_set (GnmStyle const *style, GnmStyleElement elem)
  * gnm_style_is_complete:
  * @style: #GnmStyle to query
  *
- * Returns TRUE if all elements are set.
+ * Returns: %TRUE if all elements are set.
  **/
 gboolean
 gnm_style_is_complete (GnmStyle const *style)
diff --git a/src/parse-util.c b/src/parse-util.c
index 049e92bf5..eea086ce8 100644
--- a/src/parse-util.c
+++ b/src/parse-util.c
@@ -954,7 +954,7 @@ unquote (char *dst, char const *src, int n)
  * @start:
  * @wb:
  *
- * Returns : NULL if there is a valid workbook name but it is unknown.
+ * Returns: %NULL if there is a valid workbook name but it is unknown.
  *           If the string is a valid workbook known name it returns a pointer
  *           the end of the name.
  *           Otherwise returns @start and does not modify @wb.
diff --git a/src/selection.c b/src/selection.c
index 8dad6c175..29d52b833 100644
--- a/src/selection.c
+++ b/src/selection.c
@@ -218,7 +218,7 @@ sv_is_colrow_selected (SheetView const *sv, int colrow, gboolean is_col)
 /**
  * sv_is_full_colrow_selected:
  * @sv:
- * @is_cols:
+ * @is_cols: %TRUE for columns, %FALSE for rows.
  * @index: index of column or row, -1 for any.
  *
  * Returns: %TRUE if all of the selected cols/rows in the selection
diff --git a/src/sheet-view.c b/src/sheet-view.c
index fd8fd4045..e4d3cd7ab 100644
--- a/src/sheet-view.c
+++ b/src/sheet-view.c
@@ -854,7 +854,7 @@ gnm_sheet_view_freeze_panes (SheetView *sv,
 /**
  * gnm_sheet_view_panes_insdel_colrow:
  * @sv:
- * @is_cols:
+ * @is_cols: %TRUE for columns, %FALSE for rows.
  * @is_insert:
  * @start:
  * @count:
diff --git a/src/sheet.c b/src/sheet.c
index 704bacab5..5ac6f5d42 100644
--- a/src/sheet.c
+++ b/src/sheet.c
@@ -1,4 +1,3 @@
-
 /*
  * sheet.c: Implements the sheet management and per-sheet storage
  *
@@ -1179,6 +1178,16 @@ gnm_sheet_valid_size (int cols, int rows)
 		);
 }
 
+/**
+ * gnm_sheet_suggest_size:
+ * @cols: (inout): number of columns
+ * @rows: (inout): number of rows
+ *
+ * This function produces a valid sheet valid that is reasonable for data
+ * of @cols columns by @rows rows.  If possible, this will be a size bigger
+ * in both dimensions.  However, that is not always possible and when it is
+ * not, the suggested will be smaller in one or both directions.
+ */
 void
 gnm_sheet_suggest_size (int *cols, int *rows)
 {
@@ -1449,7 +1458,7 @@ gnm_sheet_resize_main (Sheet *sheet, int cols, int rows,
  * @cols: the new columns number.
  * @rows: the new rows number.
  * @cc: #GOCmdContext.
- * @perr: will be %TRUE on error.
+ * @perr: (out): will be %TRUE on error.
  *
  * Returns: (transfer full): the newly allocated #GOUndo.
  **/
@@ -1503,6 +1512,7 @@ gnm_sheet_resize (Sheet *sheet, int cols, int rows,
  *
  * Create a new Sheet of type @type, and associate it with @wb.
  * The type cannot be changed later.
+ *
  * Returns: (transfer full): the newly allocated sheet.
  **/
 Sheet *
@@ -1539,6 +1549,7 @@ sheet_new_with_type (Workbook *wb, char const *name, GnmSheetType type,
  *
  * Create a new Sheet of type SHEET_DATA, and associate it with @wb.
  * The type can not be changed later
+ *
  * Returns: (transfer full): the newly allocated sheet.
  **/
 Sheet *
@@ -1651,7 +1662,7 @@ sheet_cell_calc_span (GnmCell *cell, GnmSpanCalcFlags flags)
 	sheet = cell->base.sheet;
 	row = cell->pos.row;
 
-	/* Render & Size any unrendered cells */
+	/* Render and Size any unrendered cells */
 	if ((flags & GNM_SPANCALC_RENDER) && gnm_cell_get_rendered_value (cell) == NULL)
 		render = TRUE;
 
@@ -1778,8 +1789,8 @@ sheet_apply_style_cb (GnmSheetRange *sr,
 
 /**
  * sheet_apply_style_undo:
- * @sr: #GnmSheetRange
- * @style: #GnmStyle
+ * @sr: (transfer full): #GnmSheetRange
+ * @style: (transfer none): #GnmStyle
  *
  * Returns: (transfer full): the new #GOUndo.
  **/
@@ -1890,7 +1901,7 @@ sheet_flag_status_update_cell (GnmCell const *cell)
 /**
  * sheet_flag_status_update_range:
  * @sheet:
- * @range: If NULL then force an update.
+ * @range: (nullable): GnmRange, or %NULL for full sheet
  *
  *    flag the sheet as requiring an update to the status display
  *    if the supplied cell location contains the edit cursor, or intersects of
@@ -1944,8 +1955,8 @@ cb_outline_level (GnmColRowIter const *iter, gpointer data)
 
 /**
  * sheet_colrow_fit_gutter:
- * @sheet: Sheet to change for.
- * @is_cols: Column gutter or row gutter?
+ * @sheet: Sheet to change.
+ * @is_cols: %TRUE for columns, %FALSE for rows.
  *
  * Find the current max outline level.
  **/
@@ -2134,10 +2145,10 @@ sheet_cell_fetch (Sheet *sheet, int col, int row)
  * sheet_colrow_can_group:
  * @sheet: #Sheet
  * @r: A #GnmRange
- * @is_cols: boolean
+ * @is_cols: %TRUE for columns, %FALSE for rows.
  *
- * Returns TRUE if the cols/rows in @r.start -> @r.end can be grouped, return
- * FALSE otherwise. You can invert the result if you need to find out if a
+ * Returns: %TRUE if the cols/rows in @r.start -> @r.end can be grouped,
+ * %FALSE otherwise. You can invert the result if you need to find out if a
  * group can be ungrouped.
  **/
 gboolean
@@ -2214,7 +2225,7 @@ sheet_colrow_group_ungroup (Sheet *sheet, GnmRange const *r,
 /**
  * sheet_colrow_gutter:
  * @sheet:
- * @is_cols:
+ * @is_cols: %TRUE for columns, %FALSE for rows.
  * @max_outline:
  *
  * Set the maximum outline levels for cols or rows.
@@ -2259,7 +2270,7 @@ cb_sheet_get_extent (G_GNUC_UNUSED gpointer ignored, gpointer value, gpointer da
 			return;
 	}
 
-	/* Remember the first cell is the min & max */
+	/* Remember the first cell is the min and max */
 	if (res->range.start.col > cell->pos.col)
 		res->range.start.col = cell->pos.col;
 	if (res->range.end.col < cell->pos.col)
@@ -2357,7 +2368,7 @@ sheet_get_extent (Sheet const *sheet, gboolean spans_and_merges_extend, gboolean
  * sheet_get_cells_extent:
  * @sheet: the sheet
  *
- * calculates the area occupied by cells, including empty cells.
+ * Calculates the area occupied by cells, including empty cells.
  *
  * Return value: the range.
  **/
@@ -2425,9 +2436,9 @@ sheet_get_nominal_printarea (Sheet const *sheet)
 }
 
 GnmRange
-sheet_get_printarea	(Sheet const *sheet,
-			 gboolean include_styles,
-			 gboolean ignore_printarea)
+sheet_get_printarea (Sheet const *sheet,
+		     gboolean include_styles,
+		     gboolean ignore_printarea)
 {
 	static GnmRange const dummy = { { 0,0 }, { 0,0 } };
 	GnmRange print_area;
@@ -2775,8 +2786,8 @@ sheet_range_set_expr_cb (GnmSheetRange const *sr, GnmExprTop const *texpr)
 
 /**
  * sheet_range_set_expr_undo:
- * @sr: #GnmSheetRange
- * @texpr: #GnmExprTop
+ * @sr: (transfer full): #GnmSheetRange
+ * @texpr: (transfer none): #GnmExprTop
  *
  * Returns: (transfer full): the newly created #GOUndo.
  **/
@@ -2863,8 +2874,8 @@ sheet_range_set_text_cb (GnmSheetRange const *sr, gchar const *text)
 
 /**
  * sheet_range_set_text_undo:
- * @sr: #GnmSheetRange
- * @text:
+ * @sr: (transfer full): #GnmSheetRange
+ * @text: (transfer none): text for range
  *
  * Returns: (transfer full): the newly created #GOUndo.
  **/
@@ -2918,10 +2929,10 @@ sheet_range_set_markup_cb (GnmSheetRange const *sr, PangoAttrList *markup)
 
 /**
  * sheet_range_set_markup_undo:
- * @sr: #GnmSheetRange
- * @markup: #PangoAttrList
+ * @sr: (transfer full): #GnmSheetRange
+ * @markup: (transfer none) (nullable): #PangoAttrList
  *
- * Returns: (transfer full): the newly created #GOUndo.
+ * Returns: (transfer full) (nullable): the newly created #GOUndo.
  **/
 GOUndo *
 sheet_range_set_markup_undo (GnmSheetRange *sr, PangoAttrList *markup)
@@ -2941,7 +2952,8 @@ sheet_range_set_markup_undo (GnmSheetRange *sr, PangoAttrList *markup)
  * @col: Source column
  * @row: Source row
  *
- * Returns: (transfer none) (nullable): the cell's current value.
+ * Returns: (transfer none) (nullable): the cell's current value.  The return
+ * value will be %NULL only when the cell does not exist.
  **/
 GnmValue const *
 sheet_cell_get_value (Sheet *sheet, int const col, int const row)
@@ -3046,6 +3058,8 @@ sheet_cell_set_text_gi (Sheet *sheet, int col, int row, char const *str)
 
 /**
  * sheet_cell_set_expr:
+ * @cell: #GnmCell
+ * @texpr: New expression for @cell.
  *
  * Marks the sheet as dirty
  * Clears old spans.
@@ -3248,23 +3262,24 @@ sheet_row_is_hidden (Sheet const *sheet, int row)
 
 /**
  * sheet_find_boundary_horizontal:
- * @sheet:  The Sheet
+ * @sheet: The Sheet
  * @col: The column from which to begin searching.
  * @move_row: The row in which to search for the edge of the range.
  * @base_row: The height of the area being moved.
  * @count:      units to extend the selection vertically
  * @jump_to_boundaries: Jump to range boundaries.
  *
- * Calculate the column index for the column which is @n units
+ * Calculate the column index for the column which is @count units
  * from @start_col doing bounds checking.  If @jump_to_boundaries is
- * TRUE @n must be 1 and the jump is to the edge of the logical range.
+ * %TRUE then @count must be 1 and the jump is to the edge of the logical range.
  *
- * NOTE : This routine implements the logic necasary for ctrl-arrow style
- * movement.  That is more compilcated than simply finding the last in a list
+ * This routine implements the logic necasary for ctrl-arrow style
+ * movement.  That is more complicated than simply finding the last in a list
  * of cells with content.  If you are at the end of a range it will find the
  * start of the next.  Make sure that is the sort of behavior you want before
  * calling this.
- * Returns: the column inex.
+ *
+ * Returns: the column index.
  **/
 int
 sheet_find_boundary_horizontal (Sheet *sheet, int start_col, int move_row,
@@ -3349,22 +3364,23 @@ sheet_find_boundary_horizontal (Sheet *sheet, int start_col, int move_row,
 
 /**
  * sheet_find_boundary_vertical:
- * @sheet:  The Sheet *
+ * @sheet: The Sheet
  * @move_col: The col in which to search for the edge of the range.
  * @row: The row from which to begin searching.
  * @base_col: The width of the area being moved.
- * @count:      units to extend the selection vertically
+ * @count: units to extend the selection vertically
  * @jump_to_boundaries: Jump to range boundaries.
  *
- * Calculate the row index for the row which is @n units
+ * Calculate the row index for the row which is @count units
  * from @start_row doing bounds checking.  If @jump_to_boundaries is
- * TRUE @n must be 1 and the jump is to the edge of the logical range.
+ * %TRUE then @count must be 1 and the jump is to the edge of the logical range.
  *
- * NOTE : This routine implements the logic necasary for ctrl-arrow style
- * movement.  That is more compilcated than simply finding the last in a list
+ * This routine implements the logic necasary for ctrl-arrow style
+ * movement.  That is more complicated than simply finding the last in a list
  * of cells with content.  If you are at the end of a range it will find the
  * start of the next.  Make sure that is the sort of behavior you want before
  * calling this.
+ *
  * Returns: the row index.
  **/
 int
@@ -3527,9 +3543,9 @@ cb_check_array_vertical (GnmColRowIter const *iter, gpointer data_)
  *
  * Check the outer edges of range @sheet!@r to ensure that if an array is
  * within it then the entire array is within the range.  @ignore is useful when
- * src & dest ranges may overlap.
+ * src and dest ranges may overlap.
  *
- * Returns: TRUE if an array would be split.
+ * Returns: %TRUE if an array would be split.
  **/
 gboolean
 sheet_range_splits_array (Sheet const *sheet,
@@ -3724,7 +3740,7 @@ sheet_range_contains_merges_or_arrays (Sheet const *sheet, GnmRange const *r,
 /**
  * sheet_colrow_get_default:
  * @sheet:
- * @is_cols:
+ * @is_cols: %TRUE for columns, %FALSE for rows.
  *
  * Returns: (transfer none): the default #ColRowInfo.
  */
@@ -4359,7 +4375,7 @@ cb_fail_if_exist (GnmCellIter const *iter, G_GNUC_UNUSED gpointer user)
  * @sheet: sheet to check
  * @r: region to check
  *
- * Returns TRUE if the specified region of the @sheet does not
+ * Returns: %TRUE if the specified region of the @sheet does not
  * contain any cells
  */
 gboolean
@@ -5532,7 +5548,7 @@ sheet_move_range (GnmExprRelocateInfo const *rinfo,
 	/* Reverse list so that we start at the top left (simplifies arrays). */
 	cells = g_list_reverse (cells);
 
-	/* 4. Clear the target area & invalidate references to it */
+	/* 4. Clear the target area and invalidate references to it */
 	if (!out_of_range)
 		/* we can clear content but not styles from the destination
 		 * region without worrying if it overlaps with the source,
@@ -5686,7 +5702,7 @@ sheet_col_get_distance_pixels (Sheet const *sheet, int from, int to)
  * @sheet:	 The sheet
  * @col:	 The col
  * @width_pts:	 The desired widtht in pts
- * @set_by_user: TRUE if this was done by a user (ie, user manually
+ * @set_by_user: %TRUE if this was done by a user (ie, user manually
  *               set the width)
  *
  * Sets width of a col in pts, INCLUDING left and right margins, and the far
@@ -5879,7 +5895,7 @@ sheet_row_get_distance_pixels (Sheet const *sheet, int from, int to)
  * @sheet:	 The sheet
  * @row:	 The row
  * @height_pts:	 The desired height in pts
- * @set_by_user: TRUE if this was done by a user (ie, user manually
+ * @set_by_user: %TRUE if this was done by a user (ie, user manually
  *               set the height)
  *
  * Sets height of a row in pts, INCLUDING top and bottom margins, and the lower
@@ -5913,7 +5929,7 @@ sheet_row_set_size_pts (Sheet *sheet, int row, double height_pts,
  * @sheet:	 The sheet
  * @row:	 The row
  * @height_pixels: The desired height
- * @set_by_user: TRUE if this was done by a user (ie, user manually
+ * @set_by_user: %TRUE if this was done by a user (ie, user manually
  *                      set the width)
  *
  * Sets height of a row in pixels, INCLUDING top and bottom margins, and the lower
@@ -6240,7 +6256,7 @@ sheet_dup (Sheet const *src)
 /**
  * sheet_set_outline_direction:
  * @sheet: the sheet
- * @is_cols: use cols or rows
+ * @is_cols: %TRUE for columns, %FALSE for rows.
  *
  * When changing the placement of outline collapse markers the flags
  * need to be recomputed.
@@ -6367,7 +6383,7 @@ cb_find_extents (GnmCellIter const *iter, GnmCellPos *extent)
  * right hand or bottom edges of the range
  * depending on the value of @cols or @rows.
  *
- * Return value: TRUE if the range was totally empty.
+ * Returns: %TRUE if the range was totally empty.
  **/
 gboolean
 sheet_range_trim (Sheet const *sheet, GnmRange *r,
@@ -6401,7 +6417,7 @@ sheet_range_trim (Sheet const *sheet, GnmRange *r,
  * header row from the top and if false it looks for a header col from the
  * left
  *
- * Returns: TRUE if @src seems to have a heading
+ * Returns: %TRUE if @src seems to have a heading
  **/
 gboolean
 sheet_range_has_heading (Sheet const *sheet, GnmRange const *src,
diff --git a/src/stf-export.c b/src/stf-export.c
index e79977697..8740f6080 100644
--- a/src/stf-export.c
+++ b/src/stf-export.c
@@ -394,9 +394,8 @@ gnm_stf_export (GnmStfExport *stfe)
 /**
  * gnm_stf_export_can_transliterate:
  *
- * Return value: TRUE iff //TRANSLIT is supported
+ * Return value: %TRUE iff //TRANSLIT is supported
  **/
-
 gboolean
 gnm_stf_export_can_transliterate (void)
 {
diff --git a/src/stf-parse.c b/src/stf-parse.c
index 5357e0850..11009b90a 100644
--- a/src/stf-parse.c
+++ b/src/stf-parse.c
@@ -472,7 +472,7 @@ stf_parse_options_fixed_splitpositions_nth (StfParseOptions_t *parseoptions, int
  *
  * Checks if @parseoptions is correctly filled
  *
- * returns : TRUE if it is correctly filled, FALSE otherwise.
+ * Returns: %TRUE if it is correctly filled, %FALSE otherwise.
  **/
 static gboolean
 stf_parse_options_valid (StfParseOptions_t *parseoptions)
@@ -523,7 +523,7 @@ trim_spaces_inplace (char *field, StfParseOptions_t const *parseoptions)
 /**
  * stf_parse_csv_is_separator:
  *
- * returns NULL if @character is not a separator, a pointer to the character
+ * Returns: %NULL if @character is not a separator, a pointer to the character
  * after the separator otherwise.
  **/
 static char const *
diff --git a/src/style-conditions.c b/src/style-conditions.c
index af95d3851..9f8ec167c 100644
--- a/src/style-conditions.c
+++ b/src/style-conditions.c
@@ -89,7 +89,7 @@ gnm_style_cond_op_operands (GnmStyleCondOp op)
  * gnm_style_cond_is_valid:
  * @cond: #GnmStyleCond
  *
- * Returns: TRUE if @cond is in a reasonable state
+ * Returns: %TRUE if @cond is in a reasonable state
  **/
 gboolean
 gnm_style_cond_is_valid (GnmStyleCond const *cond)
diff --git a/src/tools/dao.c b/src/tools/dao.c
index f9c308b24..8b5963c0b 100644
--- a/src/tools/dao.c
+++ b/src/tools/dao.c
@@ -928,7 +928,7 @@ dao_set_border (data_analysis_output_t *dao, int col1, int row1,
 /**
  * dao_get_colrow_state_list:
  * @dao:
- * @is_cols:
+ * @is_cols: %TRUE for columns, %FALSE for rows.
  *
  *
  * Returns: (transfer full):
@@ -957,11 +957,9 @@ dao_get_colrow_state_list (data_analysis_output_t *dao, gboolean is_cols)
 /**
  * dao_set_colrow_state_list:
  * @dao:
- * @is_cols:
+ * @is_cols: %TRUE for columns, %FALSE for rows.
  * @list:
  *
- *
- *
  **/
 void
 dao_set_colrow_state_list (data_analysis_output_t *dao, gboolean is_cols,
diff --git a/src/wbc-gtk.c b/src/wbc-gtk.c
index 9ebc88064..22bb70ca9 100644
--- a/src/wbc-gtk.c
+++ b/src/wbc-gtk.c
@@ -1878,7 +1878,7 @@ wbcg_close_if_user_permits (WBCGtk *wbcg, WorkbookView *wb_view)
  * wbc_gtk_close:
  * @wbcg: #WBCGtk
  *
- * Returns TRUE if the control should NOT be closed.
+ * Returns: %TRUE if the control should NOT be closed.
  */
 gboolean
 wbc_gtk_close (WBCGtk *wbcg)
diff --git a/src/widgets/gnm-expr-entry.c b/src/widgets/gnm-expr-entry.c
index 9b112509c..9791668fc 100644
--- a/src/widgets/gnm-expr-entry.c
+++ b/src/widgets/gnm-expr-entry.c
@@ -2510,12 +2510,13 @@ gnm_expr_entry_load_from_range (GnmExprEntry *gee,
 /**
  * gnm_expr_entry_get_rangesel:
  * @gee: a #GnmExprEntry
- * @r:          address to receive #GnmRange
- * @sheet:      address to receive #sheet
+ * @r: (out): address to receive #GnmRange
+ * @sheet: (out) (optional) (transfer none): address to receive #sheet
  *
  * Get the range selection. GnmRange is copied, Sheet is not. If sheet
  * argument is NULL, the corresponding value is not returned.
- * Returns TRUE if the returned range is indeed valid.
+ *
+ * Returns: %TRUE if the returned range is indeed valid.
  * The resulting range is normalized.
  **/
 gboolean
@@ -2552,7 +2553,7 @@ gnm_expr_entry_get_rangesel (GnmExprEntry const *gee,
  * gnm_expr_entry_can_rangesel:
  * @gee:   a #GnmExprEntry
  *
- * Returns TRUE if a range selection is meaningful at current position.
+ * Returns: %TRUE if a range selection is meaningful at current position.
  **/
 gboolean
 gnm_expr_entry_can_rangesel (GnmExprEntry *gee)
-- 
2.11.4.GIT