diff --git a/src/application.c b/src/application.c
index 3012544..cce60db 100644
--- a/src/application.c
+++ b/src/application.c
@@ -210,7 +210,6 @@ gnm_app_clipboard_unant (void)
 
 /**
  * gnm_app_clipboard_cut_copy:
- *
  * @wbc: the workbook control that requested the operation.
  * @is_cut: is this a cut or a copy.
  * @sv: The source sheet for the copy.
diff --git a/src/cell.c b/src/cell.c
index 3ec16a0..e5bc441 100644
--- a/src/cell.c
+++ b/src/cell.c
@@ -133,7 +133,10 @@ gnm_cell_assign_value (GnmCell *cell, GnmValue *v)
 }
 
 /**
- * gnm_cell_set_value: Stores (WITHOUT COPYING) the supplied value.  It marks the
+ * gnm_cell_set_value:
+ * @c: #GnmCell
+ * @v: #GnmValue
+ * Stores (WITHOUT COPYING) the supplied value.  It marks the
  *          sheet as dirty.
  *
  * WARNING : This is an internal routine that does not
@@ -158,8 +161,14 @@ gnm_cell_set_value (GnmCell *cell, GnmValue *v)
 	cell->value = v;
 }
 
-/*
- * gnm_cell_set_expr_and_value: Stores (WITHOUT COPYING) the supplied value, and
+/**
+ * gnm_cell_set_expr_and_value:
+ * @c: the cell to set the expr for
+ * @texpr: an expression
+ * @v:
+ * @link_expr
+ *
+ * Stores (WITHOUT COPYING) the supplied value, and
  *        references the supplied expression and links it into the expression
  *        list.  It marks the sheet as dirty. It is intended for use by import
  *        routines or operations that do bulk assignment.
@@ -169,7 +178,7 @@ gnm_cell_set_value (GnmCell *cell, GnmValue *v)
  *           not render the value.
  *
  * NOTE : This DOES check for array partitioning.
- */
+ **/
 void
 gnm_cell_set_expr_and_value (GnmCell *cell, GnmExprTop const *texpr, GnmValue *v,
 			     gboolean link_expr)
@@ -195,7 +204,7 @@ gnm_cell_set_expr_and_value (GnmCell *cell, GnmExprTop const *texpr, GnmValue *v
 /**
  * cell_set_expr_internal:
  * @cell: the cell to set the expr for
- * @expr: an expression
+ * @texpr: an expression
  *
  * A private internal utility to store an expression.
  * Does NOT
@@ -223,7 +232,11 @@ cell_set_expr_internal (GnmCell *cell, GnmExprTop const *texpr)
 }
 
 /*
- * gnm_cell_set_expr_unsafe: Stores and references the supplied expression.  It
+ * gnm_cell_set_expr_unsafe:
+ * @cell:
+ * @texpr:
+ *
+ * Stores and references the supplied expression.  It
  *         marks the sheet as dirty.  Intented for use by import routines that
  *         do bulk assignment.  The resulting cell is NOT linked into the
  *         dependent list.  Nor marked for recalc.
@@ -243,7 +256,11 @@ gnm_cell_set_expr_unsafe (GnmCell *cell, GnmExprTop const *texpr)
 }
 
 /**
- * gnm_cell_set_expr:  Stores and references the supplied expression
+ * gnm_cell_set_expr:
+ * @cell:
+ * @texpr:
+ *
+ * Stores and references the supplied expression
  *         marks the sheet as dirty.  Intented for use by import routines that
  *         do bulk assignment.  The resulting cell _is_ linked into the
  *         dependent list, but NOT marked for recalc.
@@ -362,11 +379,12 @@ gnm_cell_set_array_formula_undo (GnmSheetRange *sr, GnmExprTop const  *texpr)
 }
 
 /**
- * gnm_cell_set_array: set an array expression for a range.
+ * gnm_cell_set_array:
  * @sheet:   The sheet to set the expr in.
  * @r:       The range to set.
  * @texpr:   an expression (the inner expression, not a corner or element)
  *
+ * Set an array expression for a range.
  * Uses cell_set_expr_internal to store the expr as an
  * 'array-formula'.  The supplied expression is wrapped in an array
  * operator for each cell in the range and scheduled for recalc.
diff --git a/src/clipboard.c b/src/clipboard.c
index 52a9f15..45f6834 100644
--- a/src/clipboard.c
+++ b/src/clipboard.c
@@ -243,13 +243,13 @@ struct paste_cell_data {
 };
 
 /**
- * paste_cell: Pastes a cell in the spreadsheet
- * @dst_sheet:   The sheet where the pasting will be done
+ * paste_cell:
  * @target_col:  Column to put the cell into
  * @target_row:  Row to put the cell into.
- * @rinfo:	 A #GnmExprRelocateInfo on how to relocate content
  * @src:         A #GnmCelCopy with the content to paste
  * @paste_flags: Bit mask that describes the paste options.
+ *
+ *  Pastes a cell in the spreadsheet.
  */
 static void
 paste_cell (int target_col, int target_row,
diff --git a/src/colrow.c b/src/colrow.c
index 9763249..7fcb49f 100644
--- a/src/colrow.c
+++ b/src/colrow.c
@@ -757,7 +757,7 @@ colrow_restore_state_group (Sheet *sheet, gboolean is_cols,
 }
 
 /**
- * rows_height_update
+ * rows_height_update:
  * @sheet:  The sheet,
  * @range:  The range whose rows should be resized.
  * @shrink: If set to FALSE, rows will never shrink!
diff --git a/src/command-context-stderr.c b/src/command-context-stderr.c
index e7c71ae..f207c42 100644
--- a/src/command-context-stderr.c
+++ b/src/command-context-stderr.c
@@ -26,6 +26,7 @@ typedef GObjectClass CmdContextStderrClass;
 
 /**
  * cmd_context_stderr_new:
+ *
  * Returns: (transfer full): the newly allocated #GOCmdContext.
  **/
 GOCmdContext *
diff --git a/src/commands.c b/src/commands.c
index a9ec82c..0aaa593 100644
--- a/src/commands.c
+++ b/src/commands.c
@@ -177,6 +177,12 @@ gnm_cmd_trunc_descriptor (GString *src, gboolean *truncated)
 
 
 /**
+ * cmd_cell_range_is_locked_effective:
+ * @sheet: #Sheet
+ * @range: #GnmRange
+ * @wbc: #WorkbookControl
+ * @cmd_name: the command name.
+ *
  * checks whether the cells are effectively locked
  *
  * static gboolean cmd_cell_range_is_locked_effective
@@ -210,7 +216,7 @@ cmd_cell_range_is_locked_effective (Sheet *sheet, GnmRange *range,
 	return FALSE;
 }
 
-/**
+/*
  * checks whether the cells are effectively locked
  *
  * static gboolean cmd_dao_is_locked_effective
@@ -303,11 +309,11 @@ select_selection (Sheet *sheet, GSList *selection, WorkbookControl *wbc)
 }
 
 /**
- * get_menu_label : Utility routine to get the descriptor associated
+ * get_menu_label:
  *     with a list of commands.
- *
  * @cmd_list : The command list to check.
  *
+ * Utility routine to get the descriptor associated
  * Returns : A static reference to a descriptor.  DO NOT free this.
  */
 static char const *
@@ -322,9 +328,10 @@ get_menu_label (GSList *cmd_list)
 }
 
 /**
- * undo_redo_menu_labels : Another utility to set the menus correctly.
+ * undo_redo_menu_labels:
+ * @wb: The book whose undo/redo queues we are modifying
  *
- * workbook : The book whose undo/redo queues we are modifying
+ * Another utility to set the menus correctly.
  */
 static void
 undo_redo_menu_labels (Workbook *wb)
@@ -417,8 +424,10 @@ command_undo (WorkbookControl *wbc)
 }
 
 /**
- * command_redo : Redo the last command that was undone.
+ * command_redo:
  * @wbc: The workbook control which issued the request.
+ *
+ *  Redo the last command that was undone.
  *        Any user level errors generated by redoing will be reported
  *        here.
  **/
@@ -471,9 +480,11 @@ command_redo (WorkbookControl *wbc)
 }
 
 /**
- * command_repeat : Repeat the last command (if possible)
- *
+ * command_repeat:
  * @wbc: The workbook control which issued the request.
+ *
+ *  Repeat the last command (if possible)
+ *
  *        Any user level errors generated by redoing will be reported
  *        here.
  **/
@@ -636,11 +647,12 @@ truncate_undo_info (Workbook *wb)
 
 
 /**
- * command_register_undo : An internal utility to tack a new command
- *    onto the undo list.
- *
+ * command_register_undo:
  * @wbc : The workbook control that issued the command.
  * @cmd : The new command to add.
+ *
+ * An internal utility to tack a new command
+ *    onto the undo list.
  */
 static void
 command_register_undo (WorkbookControl *wbc, GObject *obj)
@@ -674,12 +686,13 @@ command_register_undo (WorkbookControl *wbc, GObject *obj)
 
 
 /**
- * gnm_command_push_undo : An internal utility to tack a new command
- *    onto the undo list.
- *
+ * gnm_command_push_undo:
  * @wbc: The workbook control that issued the command.
  * @obj: The new command to add.
  *
+ *  An internal utility to tack a new command
+ *    onto the undo list.
+ *
  * returns : TRUE if there was an error.
  */
 gboolean
diff --git a/src/consolidate.c b/src/consolidate.c
index 4fa8e5e..c95849b 100644
--- a/src/consolidate.c
+++ b/src/consolidate.c
@@ -345,6 +345,8 @@ retrieve_row_tree (GnmConsolidate *cs)
 }
 
 /**
+ * retrieve_col_tree:
+ *
  * Same as retrieve_row_tree, but for cols
  **/
 static GTree *
@@ -455,6 +457,8 @@ key_list_get (GnmConsolidate *cs, gboolean is_cols)
  **********************************************************************************/
 
 /**
+ * simple_consolidate:
+ *
  * This routine consolidates all the ranges in source into
  * the region dst using the function "fd" on all the overlapping
  * src regions.
@@ -599,7 +603,7 @@ row_consolidate (GnmConsolidate *cs, data_analysis_output_t *dao)
 }
 
 /**
- * cb_col_tree
+ * cb_col_tree:
  *
  * Consolidates a list of regions which all specify a single
  * column and share the same key into a single target range.
diff --git a/src/dependent.c b/src/dependent.c
index b0a1286..2536356 100644
--- a/src/dependent.c
+++ b/src/dependent.c
@@ -364,9 +364,9 @@ dependent_changed (GnmDependent *dep)
 }
 
 /**
- * dependent_set_expr :
- * @dep : The dependent we are interested in.
- * @new_expr : new expression.
+ * dependent_set_expr:
+ * @dep: The dependent we are interested in.
+ * @new_texpr: new expression.
  *
  * When the expression associated with @dep needs to change this routine
  * dispatches to the virtual handler, unlinking @dep if necessary beforehand.
@@ -407,9 +407,9 @@ dependent_pos (GnmDependent const *dep)
 
 
 /**
- * dependent_set_sheet
- * @dep :
- * @sheet :
+ * dependent_set_sheet:
+ * @dep:
+ * @sheet:
  */
 void
 dependent_set_sheet (GnmDependent *dep, Sheet *sheet)
@@ -1772,10 +1772,9 @@ cb_single_contained_depend (gpointer key,
 }
 
 /**
- * sheet_region_queue_recalc :
- *
- * @sheet : The sheet.
- * @range : Optionally NULL range.
+ * sheet_region_queue_recalc:
+ * @sheet: The sheet.
+ * @range: Optionally NULL range.
  *
  * Queues things that depend on @sheet!@range for recalc.
  *
diff --git a/src/expr-name.c b/src/expr-name.c
index 5c8d8a3..5132cb9 100644
--- a/src/expr-name.c
+++ b/src/expr-name.c
@@ -77,7 +77,7 @@ expr_name_validate_a1 (const char *name)
  * 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.
  */
 gboolean
 expr_name_validate (const char *name)
@@ -409,10 +409,12 @@ gnm_named_expr_collection_foreach (GnmNamedExprCollection *names,
 /******************************************************************************/
 
 /**
- * expr_name_handle_references : register or unregister a name with
- *    all of the sheets it explicitly references.  This is necessary
- *    because names are not dependents, and if they reference a deleted
- *    sheet we will not notice.
+ * expr_name_handle_references:
+ *
+ * Register or unregister a name with
+ * all of the sheets it explicitly references.  This is necessary
+ * because names are not dependents, and if they reference a deleted
+ * sheet we will not notice.
  */
 static void
 expr_name_handle_references (GnmNamedExpr *nexpr, gboolean add)
@@ -454,10 +456,11 @@ expr_name_handle_references (GnmNamedExpr *nexpr, gboolean add)
 
 /**
  * expr_name_lookup:
- * @pp :
- * @name :
+ * @pp:
+ * @name:
  *
  * lookup but do not reference a named expression.
+ * Returns: (transfer none): the found expression or %NULL.
  */
 GnmNamedExpr *
 expr_name_lookup (GnmParsePos const *pp, char const *name)
@@ -481,9 +484,11 @@ expr_name_lookup (GnmParsePos const *pp, char const *name)
 }
 
 /**
- * expr_name_new :
+ * expr_name_new:
+ * @name:
  *
  * Creates a new name without linking it into any container.
+ * Returns: (transfer full): the new expression.
  **/
 GnmNamedExpr *
 expr_name_new (char const *name)
@@ -608,6 +613,8 @@ expr_name_queue_deps (GnmNamedExpr *nexpr)
  *    own.
  * 2) if @link_to_container is FALSE the caller DOES OWN a reference, and
  *    can free the result by unrefing the name.
+ *
+ * Returns: (transfer none):
  **/
 GnmNamedExpr *
 expr_name_add (GnmParsePos const *pp, char const *name,
@@ -743,8 +750,8 @@ gnm_named_expr_get_type (void)
 }
 
 /**
- * expr_name_remove :
- * @nexpr :
+ * expr_name_remove:
+ * @nexpr:
  *
  * Remove a @nexpr from its container and deactivate it.
  * NOTE : @nexpr may continue to exist if things still have references to it,
@@ -775,11 +782,11 @@ expr_name_name (GnmNamedExpr const *nexpr)
 }
 
 /**
- * expr_name_set_name :
- * @nexpr : the named expression
- * @new_name : the new name of the expression
+ * expr_name_set_name:
+ * @nexpr: the named expression
+ * @new_name: the new name of the expression
  *
- * returns: TRUE on error.
+ * Returns: TRUE on error.
  */
 gboolean
 expr_name_set_name (GnmNamedExpr *nexpr,
@@ -826,11 +833,11 @@ expr_name_set_name (GnmNamedExpr *nexpr,
 
 
 /**
- * expr_name_as_string :
- * @nexpr :
- * @pp : optionally null.
+ * expr_name_as_string:
+ * @nexpr:
+ * @pp: optionally null.
  *
- * returns a string that the caller needs to free.
+ * Returns: (transfer full): a string that the caller needs to free.
  */
 char *
 expr_name_as_string (GnmNamedExpr const *nexpr, GnmParsePos const *pp,
@@ -879,8 +886,8 @@ expr_name_downgrade_to_placeholder (GnmNamedExpr *nexpr)
  * @nexpr: the named expression
  * @pp: the new position
  *
- * Returns a translated error string which the caller must free if something
- * goes wrong.
+ * Returns: (transfer full): a translated error string which the caller must
+ * free if something goes wrong.
  **/
 char *
 expr_name_set_pos (GnmNamedExpr *nexpr, GnmParsePos const *pp)
@@ -915,10 +922,9 @@ expr_name_set_pos (GnmNamedExpr *nexpr, GnmParsePos const *pp)
 }
 
 /**
- * expr_name_set_expr :
- * @nexpr : the named expression
- * @new_expr : the new content
- * @rwinfo : optional.
+ * expr_name_set_expr:
+ * @ne: the named expression
+ * @texpr: the new content
  *
  * Unrefs the current content of @nexpr and absorbs a ref to @new_expr.
  **/
@@ -986,8 +992,8 @@ expr_name_remove_dep (GnmNamedExpr *nexpr, GnmDependent *dep)
 }
 
 /**
- * expr_name_is_placeholder :
- * @ne :
+ * expr_name_is_placeholder:
+ * @ne:
  *
  * Returns TRUE if @ne is a placeholder for an unknown name
  **/
@@ -1049,7 +1055,7 @@ cb_expr_name_in_use (G_GNUC_UNUSED const char *name,
 }
 
 /**
- * expr_name_in_use :
+ * expr_name_in_use:
  * @nexpr: A named expression.
  *
  * Returns: TRUE, if the named expression appears to be in use.  This is an
@@ -1103,11 +1109,11 @@ expr_name_cmp_by_name (GnmNamedExpr const *a, GnmNamedExpr const *b)
 }
 
 /**
- * sheet_names_check :
- * @sheet :
- * @r :
+ * sheet_names_check:
+ * @sheet:
+ * @r:
  *
- * Returns a constant string if @sheet!@r is the target of a named range.
+ * Returns: (transfer none): a constant string if @sheet!@r is the target of a named range.
  * Preference is given to workbook scope over sheet.
  **/
 char const *
diff --git a/src/expr.c b/src/expr.c
index c61cc72..2fbfe3f 100644
--- a/src/expr.c
+++ b/src/expr.c
@@ -559,7 +559,9 @@ gnm_expr_array_corner_get_type (void)
 }
 
 /**
- * gnm_expr_equal : Returns TRUE if the supplied expressions are exactly the
+ * gnm_expr_equal:
+ *
+ * Return:s TRUE if the supplied expressions are exactly the
  *   same.  No eval position is used to see if they are effectively the same.
  *   Named expressions must refer the same name, having equivalent names is
  *   insufficeient.
diff --git a/src/file-autoft.c b/src/file-autoft.c
index fdc2c25..5a3e544 100644
--- a/src/file-autoft.c
+++ b/src/file-autoft.c
@@ -100,8 +100,11 @@ category_get_templates_list (FormatTemplateCategory *category,
 }
 
 /**
- * gnumeric_xml_read_format_template_category :
+ * gnumeric_xml_read_format_template_category:
+ * @dir_name:
+ *
  * Open an XML file and read a FormatTemplateCategory
+ * Returns: (transfer full):
  */
 static FormatTemplateCategory *
 gnumeric_xml_read_format_template_category (char const *dir_name)
diff --git a/src/format-template.c b/src/format-template.c
index 5d19c21..ce457aa 100644
--- a/src/format-template.c
+++ b/src/format-template.c
@@ -52,7 +52,7 @@ attr_eq (const xmlChar *a, const char *s)
  *
  * Create a new TemplateMember
  *
- * Return value: the new TemplateMember
+ * Returns: (transfer full): the new TemplateMember
  **/
 static TemplateMember *
 format_template_member_new (void)
@@ -75,10 +75,11 @@ format_template_member_new (void)
 
 /**
  * format_template_member_clone:
+ * @member:
  *
  * Clone a template member
  *
- * Return value: a copy of @member
+ * Returns: (transfer full): a copy of @member
  **/
 static TemplateMember *
 format_template_member_clone (TemplateMember *member)
@@ -204,7 +205,7 @@ format_template_member_valid (TemplateMember const *member)
  *
  * Create a new 'empty' GnmFormatTemplate
  *
- * Return value: the new GnmFormatTemplate
+ * Returns: (transfer full): the new GnmFormatTemplate
  **/
 static GnmFormatTemplate *
 format_template_new (void)
@@ -245,6 +246,9 @@ format_template_new (void)
 
 /**
  * format_template_free:
+ * @ft: GnmFormatTemplate
+ *
+ * Frees the template.
  **/
 void
 format_template_free (GnmFormatTemplate *ft)
@@ -298,7 +302,7 @@ format_template_set_description (GnmFormatTemplate *ft, char const *description)
  *
  * Make a copy of @ft.
  *
- * Returns: transfer full): a copy of @ft
+ * Returns: (transfer full): a copy of @ft
  **/
 GnmFormatTemplate *
 format_template_clone (GnmFormatTemplate const *ft)
@@ -989,7 +993,7 @@ format_template_recalc_hash (GnmFormatTemplate *ft)
  *        you may also NOT MODIFY the GnmStyle returned.
  *        (make a copy first)
  *
- * Return value: an GnmStyle
+ * Returns: (transfer none): an GnmStyle
  **/
 GnmStyle *
 format_template_get_style (GnmFormatTemplate *ft, int row, int col)
@@ -1044,7 +1048,7 @@ cb_format_sheet_style (GnmFormatTemplate *ft, GnmRange *r, GnmStyle *mstyle, gpo
  * @cc: 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
