[gnumeric] Introspection fixes

From: Morten Welinder <mortenw src gnome org>
To: commits-list gnome org
Cc:
Subject: [gnumeric] Introspection fixes
Date: Thu, 31 May 2018 18:16:52 +0000 (UTC)
commit 039b0f52fef97edff4493431db1cb3f04efd8518
Author: Morten Welinder <terra gnome org>
Date:   Thu May 31 14:16:10 2018 -0400

    Introspection fixes

 src/commands.c                  | 77 +++++++++++++++++++++++++----------------
 src/dialogs/dialog-autoformat.c |  2 +-
 src/expr-name.c                 | 12 +++----
 src/expr.c                      |  4 +--
 src/gui-util.c                  |  4 +--
 src/parse-util.c                |  2 +-
 src/sheet-object-graph.c        |  2 +-
 src/sheet-style.c               | 33 +++++++-----------
 src/sheet.c                     | 22 ++++++------
 src/tools/dao.c                 | 35 +++++++++++++------
 src/value-sheet.c               |  6 ++--
 src/wbc-gtk-edit.c              |  9 +++--
 src/widgets/gnm-expr-entry.c    |  2 +-
 src/workbook.c                  | 10 +++---
 14 files changed, 120 insertions(+), 100 deletions(-)
---
diff --git a/src/commands.c b/src/commands.c
index d55a413ad..c451487a6 100644
--- a/src/commands.c
+++ b/src/commands.c
@@ -188,6 +188,8 @@ gnm_cmd_trunc_descriptor (GString *src, gboolean *truncated)
  *
  * Do not use this function unless the sheet is part of the
  * workbook with the given wbc (otherwise the results may be strange)
+ *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  */
 gboolean
 cmd_cell_range_is_locked_effective (Sheet *sheet, GnmRange *range,
@@ -223,8 +225,8 @@ cmd_cell_range_is_locked_effective (Sheet *sheet, GnmRange *range,
  * Do not use this function unless the sheet is part of the
  * workbook with the given wbcg (otherwise the results may be strange)
  *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  */
-
 static gboolean
 cmd_dao_is_locked_effective (data_analysis_output_t  *dao,
                             WorkbookControl *wbc, char const *cmd_name)
@@ -242,10 +244,10 @@ cmd_dao_is_locked_effective (data_analysis_output_t  *dao,
  *
  * static gboolean cmd_selection_is_locked_effective
  *
- *
  * Do not use this function unless the sheet is part of the
  * workbook with the given wbcg (otherwise the results may be strange)
  *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  */
 gboolean
 cmd_selection_is_locked_effective (Sheet *sheet, GSList *selection,
@@ -818,8 +820,8 @@ cmd_set_text_full_check_markup (GnmCellIter const *iter, PangoAttrList *markup)
  * Note:
  * We will free the selection but nothing else.
  *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  */
-
 static gboolean
 cmd_set_text_full (WorkbookControl *wbc, GSList *selection, GnmEvalPos *ep,
                   char const *new_text, PangoAttrList *markup,
@@ -1083,8 +1085,8 @@ cmd_set_text_full (WorkbookControl *wbc, GSList *selection, GnmEvalPos *ep,
  * 1) that no array is being split
  * 2) that the range is not locked.
  *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  */
-
 gboolean
 cmd_area_set_text (WorkbookControl *wbc, SheetView *sv,
                   char const *new_text, PangoAttrList *markup)
@@ -1142,8 +1144,8 @@ cmd_set_text (WorkbookControl *wbc,
  * 2) that the selection consists of a single range
  * 3) that the range is not locked.
  *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  */
-
 gboolean
 cmd_area_set_array_expr (WorkbookControl *wbc, SheetView *sv,
                         GnmExprTop const  *texpr)
@@ -1198,6 +1200,7 @@ cmd_area_set_array_expr (WorkbookControl *wbc, SheetView *sv,
  * 1) that no array is being split
  * 2) that the range is not locked.
  *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  */
 gboolean
 cmd_create_data_table (WorkbookControl *wbc, Sheet *sheet, GnmRange const *r,
@@ -1795,19 +1798,17 @@ cmd_format_finalize (GObject *cmd)
 }
 
 /**
- * cmd_format:
+ * cmd_format: (skip)
  * @wbc: the workbook control.
  * @sheet: the sheet
- * @style: style to apply to the selection
- * @borders: borders to apply to the selection
+ * @style: (transfer full): style to apply to the selection
+ * @borders: (nullable) (transfer full): borders to apply to the selection
  * @opt_translated_name: An optional name to use in place of 'Format Cells'
  *
- * If borders is non NULL, then the GnmBorder references are passed,
+ * If borders is non-%NULL, then the GnmBorder references are passed,
  * the GnmStyle reference is also passed.
  *
- * It absorbs the reference to the style.
- *
- * Return value: TRUE if there was a problem
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
 gboolean
 cmd_selection_format (WorkbookControl *wbc,
@@ -3073,7 +3074,12 @@ cmd_paste_copy_finalize (GObject *cmd)
 }
 
 /*
- * cmd_paste_copy will ref cr as needed.
+ * cmd_paste_copy:
+ * @wbc:
+ * @pt:
+ * @cr: (transfer none):
+ *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  */
 gboolean
 cmd_paste_copy (WorkbookControl *wbc,
@@ -3681,7 +3687,7 @@ cmd_autoformat_finalize (GObject *cmd)
  * @wbc: the context.
  * @ft: The format template that was applied
  *
- * Return value: TRUE if there was a problem
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
 gboolean
 cmd_selection_autoformat (WorkbookControl *wbc, GnmFT *ft)
@@ -3825,7 +3831,7 @@ cmd_unmerge_cells_finalize (GObject *cmd)
  * @sheet: #Sheet
  * @selection: (element-type GnmRange): selection.
  *
- * Return value: TRUE if there was a problem
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
 gboolean
 cmd_unmerge_cells (WorkbookControl *wbc, Sheet *sheet, GSList const *selection)
@@ -3992,7 +3998,7 @@ cmd_merge_cells_finalize (GObject *cmd)
  * @selection: (element-type GnmRange): selection.
  * @center:
  *
- * Return value: %TRUE if there was a problem
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
 gboolean
 cmd_merge_cells (WorkbookControl *wbc, Sheet *sheet, GSList const *selection,
@@ -4547,6 +4553,7 @@ cmd_zoom_finalize (GObject *cmd)
  * @sheets: (element-type Sheet) (transfer container):
  * @factor:
  *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
 gboolean
 cmd_zoom (WorkbookControl *wbc, GSList *sheets, double factor)
@@ -4664,9 +4671,9 @@ cmd_objects_store_location (SheetObject *so, GArray *location)
  * delete.
  * @name:
  *
- * Absorbs the list, adding references to the contents.
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
- gboolean
+gboolean
 cmd_objects_delete (WorkbookControl *wbc, GSList *objects,
                    char const *name)
 {
@@ -4701,6 +4708,7 @@ cmd_objects_delete (WorkbookControl *wbc, GSList *objects,
  * @objects_created:
  * @name:
  *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
 gboolean
 cmd_objects_move (WorkbookControl *wbc, GSList *objects, GSList *anchors,
@@ -4917,6 +4925,7 @@ cmd_resize_sheets_finalize (GObject *cmd)
  * @cols: new columns number.
  * @rows: new rows number.
  *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
 gboolean
 cmd_resize_sheets (WorkbookControl *wbc,
@@ -5300,8 +5309,10 @@ cmd_analysis_tool_finalize (GObject *cmd)
 
 /**
  * cmd_analysis_tool: (skip)
- * Note: this takes ownership of specs and dao if and if only the command
+ * Note: this takes ownership of specs and dao if the command
  * succeeds.
+ *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
 gboolean
 cmd_analysis_tool (WorkbookControl *wbc, G_GNUC_UNUSED Sheet *sheet,
@@ -5500,6 +5511,7 @@ cmd_merge_data_finalize (GObject *cmd)
  * @merge_fields: (element-type GnmRange) (transfer full):
  * @merge_data: (element-type GnmRange) (transfer full):
  *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
 gboolean
 cmd_merge_data (WorkbookControl *wbc, Sheet *sheet,
@@ -5604,6 +5616,7 @@ cmd_change_summary_finalize (GObject *cmd)
  * @changes: (element-type GsfDocMetaData) (transfer full): the changed metadata.
  * @removed: (element-type GsfDocMetaData) (transfer full): the removed metadata.
  *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
 gboolean
 cmd_change_meta_data (WorkbookControl *wbc, GSList *changes, GSList *removed)
@@ -5931,14 +5944,14 @@ cmd_define_name_finalize (GObject *cmd)
  * @wbc:
  * @name:
  * @pp:
- * @texpr: absorbs a ref to the texpr.
+ * @texpr: (transfer full): #GnmExprTop
  * @descriptor: optional descriptor.
  *
  * If the @name has never been defined in context @pp create a new name
  * If its a placeholder assign @texpr to it and make it real
  * If it already exists as a real name just assign @expr.
  *
- * Returns TRUE on error
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
 gboolean
 cmd_define_name (WorkbookControl *wbc, char const *name,
@@ -6164,8 +6177,9 @@ cmd_rescope_name_finalize (GObject *cmd)
  * cmd_rescope_name:
  * @wbc:
  * @nexpr: name to rescope.
+ * @scope:
  *
- * Returns TRUE on error
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
 gboolean
 cmd_rescope_name (WorkbookControl *wbc, GnmNamedExpr *nexpr, Sheet *scope)
@@ -6228,6 +6242,14 @@ cmd_scenario_add_finalize (GObject *cmd)
        gnm_command_finalize (cmd);
 }
 
+/**
+ * cmd_scenario_add: (skip)
+ * @wbc:
+ * @s: (transfer full):
+ * @sheet:
+ *
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
+ */
 gboolean
 cmd_scenario_add (WorkbookControl *wbc, GnmScenario *s, Sheet *sheet)
 {
@@ -6685,7 +6707,7 @@ cmd_freeze_panes_finalize (GObject *cmd)
  * @frozen:
  * @unfrozen:
  *
- * Returns TRUE on error
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
 gboolean
 cmd_freeze_panes (WorkbookControl *wbc, SheetView *sv,
@@ -7196,16 +7218,11 @@ cmd_hyperlink_finalize (GObject *cmd)
 /**
  * cmd_selection_hyperlink:
  * @wbc: the workbook control.
- * @style: style to apply to the selection
+ * @style: (transfer full): style to apply to the selection
  * @opt_translated_name: An optional name to use in place of 'Hyperlink Cells'
  * @opt_content: optional content for otherwise empty cells.
  *
- * If borders is non NULL, then the GnmBorder references are passed,
- * the GnmStyle reference is also passed.
- *
- * It absorbs the reference to the style.
- *
- * Return value: TRUE if there was a problem
+ * Returns: %TRUE if there was a problem, %FALSE otherwise.
  **/
 gboolean
 cmd_selection_hyperlink (WorkbookControl *wbc,
diff --git a/src/dialogs/dialog-autoformat.c b/src/dialogs/dialog-autoformat.c
index b3f83be1b..0fc973cd7 100644
--- a/src/dialogs/dialog-autoformat.c
+++ b/src/dialogs/dialog-autoformat.c
@@ -281,7 +281,7 @@ previews_free (AutoFormatState *state)
  *
  * This function will create grids and rects for each canvas and associate
  * them with the right format templates.
- * NOTE : if state->preview_locked is TRUE this function will do nothing,
+ * NOTE : if state->preview_locked is %TRUE this function will do nothing,
  *        this is handy in situation where signals can cause previews_load to be
  *        called before previews_free.
  **/
diff --git a/src/expr-name.c b/src/expr-name.c
index 956f9636f..245f1582f 100644
--- a/src/expr-name.c
+++ b/src/expr-name.c
@@ -682,11 +682,11 @@ expr_name_queue_deps (GnmNamedExpr *nexpr)
 }
 
 /**
- * expr_name_add:
+ * expr_name_add: (skip)
  * @pp:
  * @name:
  * @texpr: if texpr == NULL then create a placeholder with value #NAME?
- * @error_msg:
+ * @error_msg: (out) (optional) (nullable):
  * @link_to_container:
  *
  * Absorbs the reference to @texpr.
@@ -697,7 +697,7 @@ expr_name_queue_deps (GnmNamedExpr *nexpr)
  * 1) new names with @link_to_container TRUE are referenced by the container.
  *    The caller DOES NOT OWN a reference to the result, and needs to add their
  *    own.
- * 2) if @link_to_container is FALSE the caller DOES OWN a reference, and
+ * 2) if @link_to_container is %FALSE the caller DOES OWN a reference, and
  *    can free the result by unrefing the name.
  **/
 GnmNamedExpr *
@@ -715,6 +715,9 @@ expr_name_add (GnmParsePos const *pp, char const *name,
        g_return_val_if_fail (name != NULL, NULL);
        g_return_val_if_fail (stub == NULL || stub->is_placeholder, NULL);
 
+       if (error_msg)
+               *error_msg = NULL;
+
        fake_name.str = name;
 
        if (gnm_debug_flag ("names")) {
@@ -767,9 +770,6 @@ expr_name_add (GnmParsePos const *pp, char const *name,
                }
        }
 
-       if (error_msg)
-               *error_msg = NULL;
-
        if (nexpr == NULL) {
                if (stub != NULL) {
                        nexpr = stub;
diff --git a/src/expr.c b/src/expr.c
index b8c5b3e02..183c21029 100644
--- a/src/expr.c
+++ b/src/expr.c
@@ -2738,13 +2738,13 @@ do_expr_walk (GnmExpr const *expr, GnmExprWalkerFunc walker, GnmExprWalk *data)
  * Returns: (transfer full) (allow-none): transformed expression.
  *
  * This function walks the expression and calls the walker function for
- * each subexpression.  If the walker returns a non-NULL expression,
+ * each subexpression.  If the walker returns a non-%NULL expression,
  * a new expression is built.
  *
  * The walker will be called for an expression before its subexpressions.
  * It will receive the expression as its first argument and a GnmExprWalk
  * pointer as its second.  It may set the stop flag to terminate the walk
- * in which case gnm_expr_walk will return NULL.
+ * in which case gnm_expr_walk will return %NULL.
  **/
 GnmExpr const *
 gnm_expr_walk (GnmExpr const *expr, GnmExprWalkerFunc walker, gpointer user)
diff --git a/src/gui-util.c b/src/gui-util.c
index cfc502a6b..da70b87a2 100644
--- a/src/gui-util.c
+++ b/src/gui-util.c
@@ -460,9 +460,9 @@ kill_popup_menu (GtkWidget *widget, G_GNUC_UNUSED gpointer user)
 /**
  * gnumeric_popup_menu:
  * @menu: #GtkMenu
- * @event: #GdkEvent optionally NULL
+ * @event: (nullable): #GdkEvent
  *
- * Bring up a popup and if @event is non-NULL ensure that the popup is on the
+ * Bring up a popup and if @event is non-%NULL ensure that the popup is on the
  * right screen.
  **/
 void
diff --git a/src/parse-util.c b/src/parse-util.c
index e42f9d080..049e92bf5 100644
--- a/src/parse-util.c
+++ b/src/parse-util.c
@@ -727,7 +727,7 @@ cell_name (GnmCell const *cell)
  * @cell_str:   a string representation of a cell name.
  * @ss:          #GnmSheetSize
  * @res:         result
- * @strict:      if this is TRUE, then parsing stops at possible errors,
+ * @strict:      if this is %TRUE, then parsing stops at possible errors,
  *               otherwise an attempt is made to return cell names with
  *               trailing garbage.
  *
diff --git a/src/sheet-object-graph.c b/src/sheet-object-graph.c
index 93007ee31..b3f257c98 100644
--- a/src/sheet-object-graph.c
+++ b/src/sheet-object-graph.c
@@ -650,7 +650,7 @@ sheet_object_graph_get_gog (SheetObject *sog)
  * @sog: #SheetObjectGraph
  * @graph: (allow-none): #GogGraph
  *
- * If @graph is non NULL add a reference to it, otherwise create a new graph.
+ * If @graph is non-%NULL add a reference to it, otherwise create a new graph.
  * Assign the graph to its SheetObjectGraph wrapper and initialize the
  * handlers, disconnecting any existing connection for the preceding graph.
  **/
diff --git a/src/sheet-style.c b/src/sheet-style.c
index f61eb5e9b..7d3fdf2e5 100644
--- a/src/sheet-style.c
+++ b/src/sheet-style.c
@@ -182,10 +182,9 @@ sheet_style_unlink (Sheet *sheet, GnmStyle *st)
 /**
  * sheet_style_find:
  * @sheet: (transfer full): the sheet
- * @st: a style
+ * @st: (transfer full): a style
  *
  * Looks up a style from the sheets collection.  Linking if necessary.
- * ABSORBS the reference and adds a link.
  *
  * Returns: (transfer full): the new style.
  */
@@ -824,7 +823,6 @@ sheet_style_shutdown (Sheet *sheet)
  * @grid_color: (transfer full): The color
  *
  * Set the color for rendering auto colored patterns in this sheet.
- * Absorbs a reference to @pattern_color;
  **/
 void
 sheet_style_set_auto_pattern_color (Sheet *sheet, GnmColor *pattern_color)
@@ -1345,12 +1343,11 @@ tail_recursion:
 
 /**
  * sheet_style_set_range:
- * @sheet:
- * @range:
- * @style: #GnmStyle
+ * @sheet: #Sheet being changed
+ * @range: #GnmRange being changed
+ * @style: (transfer full): New #GnmStyle
  *
  * Change the complete style for a region.
- * This function absorbs a reference to the new @style.
  */
 void
 sheet_style_set_range (Sheet *sheet, GnmRange const *range,
@@ -1380,15 +1377,14 @@ sheet_style_set_range (Sheet *sheet, GnmRange const *range,
 
 /**
  * sheet_style_apply_col:
- * @sheet:
- * @col:
- * @style: #GnmStyle
+ * @sheet: #Sheet being changed
+ * @col: Column
+ * @style: (transfer full): #GnmStyle
  *
  * NOTE: This is a simple wrapper for now.  When we support col/row styles it
  *     will make life easier.
  *
  * Apply a partial style to a full col.
- * The routine absorbs a reference to the partial style.
  **/
 void
 sheet_style_apply_col (Sheet *sheet, int col, GnmStyle *pstyle)
@@ -1402,13 +1398,12 @@ sheet_style_apply_col (Sheet *sheet, int col, GnmStyle *pstyle)
  * sheet_style_apply_row:
  * @sheet:
  * @row:
- * @style: #GnmStyle
+ * @style: (transfer full): #GnmStyle
  *
  * NOTE: This is a simple wrapper for now.  When we support col/row styles it
  *     will make life easier.
  *
  * Apply a partial style to a full col.
- * The routine absorbs a reference to the partial style.
  **/
 void
 sheet_style_apply_row (Sheet  *sheet, int row, GnmStyle *pstyle)
@@ -1423,14 +1418,12 @@ sheet_style_apply_row (Sheet  *sheet, int row, GnmStyle *pstyle)
  * @sheet:
  * @col:
  * @row:
- * @style: #GnmStyle
+ * @style: (transfer full): #GnmStyle
  *
  * Apply a partial style to a single cell
- * This function absorbs a reference to the new @style.
  **/
 void
-sheet_style_apply_pos (Sheet *sheet, int col, int row,
-                      GnmStyle *pstyle)
+sheet_style_apply_pos (Sheet *sheet, int col, int row, GnmStyle *pstyle)
 {
        ReplacementStyle rs;
 
@@ -1447,10 +1440,9 @@ sheet_style_apply_pos (Sheet *sheet, int col, int row,
  * @sheet:
  * @col:
  * @row:
- * @style:
+ * @style: (transfer full):
  *
  * Change the complete style for a single cell.
- * This function absorbs a reference to the new @style.
  **/
 void
 sheet_style_set_pos (Sheet *sheet, int col, int row,
@@ -1754,7 +1746,6 @@ style_row_init (GnmBorder const * * *prev_vert,
  * @pstyle: (transfer full): A partial style to apply
  *
  * Apply a partial style to a region.
- * The routine absorbs a reference to the partial style.
  */
 void
 sheet_style_apply_range (Sheet *sheet, GnmRange const *range, GnmStyle *pstyle)
@@ -1785,7 +1776,7 @@ sheet_style_apply_range (Sheet *sheet, GnmRange const *range, GnmStyle *pstyle)
  * sheet_style_apply_range2: (skip)
  * @sheet: #Sheet
  * @range: #GnmRange to apply over
- * @pstyle: A partial style to apply
+ * @pstyle: (transfer none): A partial style to apply
  *
  * Apply a partial style to a region.
  */
diff --git a/src/sheet.c b/src/sheet.c
index dc36c0a3e..704bacab5 100644
--- a/src/sheet.c
+++ b/src/sheet.c
@@ -2301,7 +2301,7 @@ cb_sheet_get_extent (G_GNUC_UNUSED gpointer ignored, gpointer value, gpointer da
  *
  * calculates the area occupied by cell data.
  *
- * NOTE: When spans_and_merges_extend is TRUE, this function will calculate
+ * NOTE: When spans_and_merges_extend is %TRUE, this function will calculate
  * all spans.  That might be expensive.
  *
  * NOTE: This refers to *visible* contents.  Cells with empty values, including
@@ -3334,7 +3334,7 @@ sheet_find_boundary_horizontal (Sheet *sheet, int start_col, int move_row,
                        else if (!find_nonblank) {
                                /*
                                 * Handle special case where we are on the last
-                                * non-null cell
+                                * non-NULL cell
                                 */
                                if (iterations == 1)
                                        keep_looking = find_nonblank = TRUE;
@@ -3435,7 +3435,7 @@ sheet_find_boundary_vertical (Sheet *sheet, int move_col, int start_row,
                        else if (!find_nonblank) {
                                /*
                                 * Handle special case where we are on the last
-                                * non-null cell
+                                * non-NULL cell
                                 */
                                if (iterations == 1)
                                        keep_looking = find_nonblank = TRUE;
@@ -4041,8 +4041,8 @@ sheet_cells (Sheet *sheet, const GnmRange *r)
  * Note: this function does not honour the CELL_ITER_IGNORE_SUBTOTAL flag.
  *
  * Returns: (transfer none): the value returned by the callback, which can be:
- *    non-NULL on error, or VALUE_TERMINATE if some invoked routine requested
- *    to stop (by returning non-NULL).
+ *    non-%NULL on error, or VALUE_TERMINATE if some invoked routine requested
+ *    to stop (by returning non-%NULL).
  *
  * NOTE: between 0.56 and 0.57, the traversal order changed.  The order is now
  *
@@ -4085,8 +4085,8 @@ sheet_foreach_cell_in_range (Sheet *sheet, CellIterFlags flags,
  * Note: this function does not honour the CELL_ITER_IGNORE_SUBTOTAL flag.
  *
  * Returns: (transfer none): the value returned by the callback, which can be:
- *    non-NULL on error, or VALUE_TERMINATE if some invoked routine requested
- *    to stop (by returning non-NULL).
+ *    non-%NULL on error, or VALUE_TERMINATE if some invoked routine requested
+ *    to stop (by returning non-%NULL).
  *
  * NOTE: between 0.56 and 0.57, the traversal order changed.  The order is now
  *
@@ -4896,7 +4896,7 @@ cb_empty_cell (GnmCellIter const *iter, gpointer user)
  * @start_row:
  * @end_col:
  * @end_row:
- * @clear_flags: If this is TRUE then styles are erased.
+ * @clear_flags: If this is %TRUE then styles are erased.
  * @cc: (nullable):
  *
  * Clears are region of cells
@@ -5426,12 +5426,12 @@ cb_collect_cell (GnmCellIter const *iter, gpointer user)
  * sheet_move_range:
  * @cc:
  * @rinfo:
- * @pundo: optionally NULL, caller releases result
+ * @pundo: (out) (optional) (transfer full): undo object
  *
  * Move a range as specified in @rinfo report warnings to @cc.
- * if @pundo is non NULL, invalidate references to the
+ * if @pundo is non-%NULL, invalidate references to the
  * target region that are being cleared, and store the undo information
- * in @pundo.  If it is NULL do NOT INVALIDATE.
+ * in @pundo.  If it is %NULL do NOT INVALIDATE.
  **/
 void
 sheet_move_range (GnmExprRelocateInfo const *rinfo,
diff --git a/src/tools/dao.c b/src/tools/dao.c
index 635d95c50..f9c308b24 100644
--- a/src/tools/dao.c
+++ b/src/tools/dao.c
@@ -375,8 +375,14 @@ dao_cell_is_visible (data_analysis_output_t *dao, int col, int row)
 }
 
 
-/*
- * dao_set_cell_array_expr absorbs the reference for the expr.
+/**
+ * dao_set_array_expr: (skip)
+ * @dao:
+ * @col: starting column
+ * @row: starting row
+ * @cols: number of columns
+ * @rows: number of rows
+ * @expr: (transfer full): expression to set
  *
  */
 void
@@ -400,9 +406,15 @@ dao_set_array_expr (data_analysis_output_t *dao,
                                    r.end.col, r.end.row,
                                    texpr);
 }
-/*
- * dao_set_cell_array_expr absorbs the reference for the expr.
+
+/**
+ * dao_set_cell_array_expr: (skip)
+ * @dao:
+ * @col: column
+ * @row: row
+ * @expr: (transfer full): expression to set
  *
+ * Sets a singleton array expression.
  */
 void
 dao_set_cell_array_expr (data_analysis_output_t *dao, int col, int row,
@@ -411,11 +423,15 @@ dao_set_cell_array_expr (data_analysis_output_t *dao, int col, int row,
        dao_set_array_expr (dao, col, row, 1, 1, expr);
 }
 
-/*
- * dao_set_cell_expr absorbs the reference for the expr.
+/**
+ * dao_set_cell_expr: (skip)
+ * @dao:
+ * @col: column
+ * @row: row
+ * @expr: (transfer full): expression to set
  *
+ * Sets a singleton array expression.
  */
-
 void
 dao_set_cell_expr (data_analysis_output_t *dao, int col, int row,
                   GnmExpr const *expr)
@@ -443,16 +459,13 @@ dao_set_cell_expr (data_analysis_output_t *dao, int col, int row,
  * @dao:
  * @col:
  * @row:
- * @v:
+ * @v: (transfer full):
  *
  * set cell to a value
  *
  * Note: the rows/cols specification for all dao_set_cell_...
  *       commands are relative to the location of the output
- *
- *
  **/
-
 void
 dao_set_cell_value (data_analysis_output_t *dao, int col, int row, GnmValue *v)
 {
diff --git a/src/value-sheet.c b/src/value-sheet.c
index 8274ae3c6..230e93949 100644
--- a/src/value-sheet.c
+++ b/src/value-sheet.c
@@ -225,9 +225,9 @@ cb_wrapper_foreach_cell_in_area (GnmCellIter const *iter, WrapperClosure *wrap)
  * For each existing element in an array or range , invoke the
  * callback routine.
  *
- * Returns: (transfer none):
- *    non-NULL on error, or VALUE_TERMINATE if some invoked routine requested
- *    to stop (by returning non-NULL).
+ * Returns:
+ *    non-%NULL on error, or VALUE_TERMINATE if some the handler requested
+ *    to stop (by returning non-%NULL).
  **/
 GnmValue *
 value_area_foreach (GnmValue const *v, GnmEvalPos const *ep,
diff --git a/src/wbc-gtk-edit.c b/src/wbc-gtk-edit.c
index cd45ba09f..7df7c11f4 100644
--- a/src/wbc-gtk-edit.c
+++ b/src/wbc-gtk-edit.c
@@ -1,4 +1,3 @@
-
 /*
  * wbc-gtk-edit.c: Keeps track of the cell editing process.
  *
@@ -84,9 +83,9 @@ wbcg_auto_complete_destroy (WBCGtk *wbcg)
  * wbcg_edit_finish:
  * @wbcg: #WBCGtk
  * @result: what should we do with the content
- * @showed_dialog: If non-NULL will indicate if a dialog was displayed.
+ * @showed_dialog: (optional) (out): indicates whether a dialog was displayed.
  *
- * Return: TRUE if editing completed successfully, or we were no editing.
+ * Returns: %TRUE if editing completed successfully, or we were no editing.
  **/
 gboolean
 wbcg_edit_finish (WBCGtk *wbcg, WBCEditResult result,
@@ -823,7 +822,7 @@ cb_warn_toggled (GtkToggleButton *button, gboolean *b)
  *  1) in-cell editing when you just start typing, and
  *  2) above sheet editing when you hit F2.
  *
- * Returns TRUE if we did indeed start editing.  Returns FALSE if the
+ * Returns: %TRUE if we did indeed start editing.  Returns %FALSE if the
  * cell-to-be-edited was locked.
  */
 gboolean
@@ -1142,7 +1141,7 @@ wbcg_set_entry (WBCGtk *wbcg, GnmExprEntry *entry)
  * wbcg_entry_has_logical:
  * @wbcg: #WBCGtk
  *
- * Returns: TRUE if wbcg_set_entry has redirected the edit_entry.
+ * Returns: %TRUE if wbcg_set_entry has redirected the edit_entry.
  **/
 gboolean
 wbcg_entry_has_logical (WBCGtk const *wbcg)
diff --git a/src/widgets/gnm-expr-entry.c b/src/widgets/gnm-expr-entry.c
index 5a3cf927f..9b112509c 100644
--- a/src/widgets/gnm-expr-entry.c
+++ b/src/widgets/gnm-expr-entry.c
@@ -2232,7 +2232,7 @@ gnm_expr_entry_set_update_policy (GnmExprEntry *gee,
 
 /**
  * gnm_expr_entry_new:
- * @wbcg: #WBCGtk non-NULL
+ * @wbcg: #WBCGtk
  * @with_icon: append a rollup icon to the end of the entry
  *
  * Creates a new #GnmExprEntry, which is an entry widget with support
diff --git a/src/workbook.c b/src/workbook.c
index f641dbb15..828c2170f 100644
--- a/src/workbook.c
+++ b/src/workbook.c
@@ -554,7 +554,7 @@ workbook_set_last_export_uri (Workbook *wb, const gchar *uri)
  * workbook_foreach_cell_in_range:
  * @pos: The position the range is relative to.
  * @cell_range: A value containing a range;
- * @flags: if TRUE only existing cells are sent to the handler.
+ * @flags: flags determining whichs cells to consider
  * @handler: (scope call): The operator to apply to each cell.
  * @closure: User data.
  *
@@ -562,14 +562,14 @@ workbook_set_last_export_uri (Workbook *wb, const gchar *uri)
  * The range bounds are calculated relative to the eval position
  * and normalized.
  * For each existing cell in the range specified, invoke the
- * callback routine.  If the only_existing flag is TRUE, then
+ * callback routine.  If the only_existing flag is %TRUE, then
  * callbacks are only invoked for existing cells.
  *
  * Note: this function does not honour the CELL_ITER_IGNORE_SUBTOTAL flag.
  *
- * Return value:
- *    non-NULL on error, or VALUE_TERMINATE if some invoked routine requested
- *    to stop (by returning non-NULL).
+ * Returns:
+ *    non-%NULL on error, or VALUE_TERMINATE if some the handler requested
+ *    to stop (by returning non-%NULL).
  */
 GnmValue *
 workbook_foreach_cell_in_range (GnmEvalPos const *pos,
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]