GNOME.org
 

[gnumeric] Introspection fixes

commit d18c86095a1d42bef3a267ff31e0ed586d4ce7f8
Author: Morten Welinder <terra gnome org>
Date:   Thu Apr 19 11:49:40 2018 -0400

    Introspection fixes

 src/collect.c   |  141 ++++++++++++++++++++++++++++++++----------------------
 src/collect.h   |    2 +-
 src/expr-name.c |   67 +++++++++++++++++---------
 src/expr-name.h |    3 +-
 4 files changed, 129 insertions(+), 84 deletions(-)
---
diff --git a/src/collect.c b/src/collect.c
index 381ef1e..efb4e1e 100644
--- a/src/collect.c
+++ b/src/collect.c
@@ -602,14 +602,19 @@ collect_floats_value_with_info (GnmValue const *val, GnmEvalPos const *ep,
 
 /**
  * float_range_function:
- * @argc:
- * @argv:
- * @ei:
- * @func: (scope call):
- * @flags:
- * @func_error:
+ * @argc: number of arguments
+ * @argv: (in) (array length=argc): function arguments
+ * @ei: #GnmFuncEvalInfo describing evaluation context
+ * @func: (scope call): implementation function
+ * @flags: #CollectFlags flags describing the collection and interpretation
+ * of values from @argv.
+ * @func_error: A #GnmStdError to use to @func indicates an error.
  *
- * Returns: (transfer full):
+ * This implements a Gnumeric sheet function that operates on a list of
+ * numbers.  This function collects the arguments and uses @func to do
+ * the actual computation.
+ *
+ * Returns: (transfer full): Function result or error value.
  **/
 GnmValue *
 float_range_function (int argc, GnmExprConstPtr const *argv,
@@ -641,17 +646,14 @@ float_range_function (int argc, GnmExprConstPtr const *argv,
 
 /**
  * gnm_slist_sort_merge:
- * @list_1: (element-type void): a sorted list of ints with no duplicates
- * @list_2: (element-type void): another one
+ * @list_1: (element-type void) (transfer container): a sorted list of
+ * unsigned integers with no duplicates.
+ * @list_2: (element-type void) (transfer container): another one
  *
- * gnm_slist_sort_merge returns a new sorted list with all elements
- * from both @list_1 and @list_2. Duplicates are destroyed. @list1 and @list2
- * are not anymore valid afterwards since their elements are in the new list
- * or have been destroyed, in case of duplicates.
+ * gnm_slist_sort_merge merges two lists of unsigned integers.
  *
- * Returns: (element-type void) (transfer container): the new list.
+ * Returns: (element-type void) (transfer container): the mergedlist.
  **/
-
 GSList *
 gnm_slist_sort_merge (GSList *l1,
                      GSList *l2)
@@ -684,9 +686,13 @@ gnm_slist_sort_merge (GSList *l1,
 
 /**
  * gnm_strip_missing:
- * @data:
- * @missing: (element-type void):
+ * @data: (inout) (array length=n): Array
+ * @n: (inout): Number of elements in @data.
+ * @missing: (element-type void): indices of elements to remove in increasing
+ * order.
  *
+ * This removes the data elements from @data whose indices are given by
+ * @missing.  @n is the number of elements and it updated upon return.
  **/
 void
 gnm_strip_missing (gnm_float *data, int *n, GSList *missing)
@@ -756,21 +762,25 @@ collect_float_pairs_ce (GnmValue const *vx, GnmValue const *vy,
 }
 
 /**
- * collect_float_pairs:
+ * collect_float_pairs: (skip)
  * @v0: value describing first data range
  * @v1: value describing second data range
  * @ep: evaluation position
  * @flags: flags describing how to handle value types
- * @xs0: return location for first data vector
- * @xs1: return location for second data vector
- * @n: return location for number of data points
- * @constp: optional return location for an indicator of the return vectors
- * being owned by this function as opposed to the normal copy owned by the
- * caller.
+ * @xs0: (out) (array length=n): return location for first data vector
+ * @xs1: (out) (array length=n): return location for second data vector
+ * @n: (out): return location for number of data points
+ * @constp: (out) (optional): Return location for a flag describing who own
+ * the vectors returned in @xs0 and @xs1.  If present and %TRUE, the
+ * resulting data vectors in @xs0 and @xs1 are not owned by the caller.
+ * If not-present or %FALSE, the callers owns and must free the result.
  *
  * If @n is not positive upon return, no data has been allocated.
- * If @n is negative upon return, the two ranges had different
- * sizes.
+ * If @n is negative upon return, the two ranges had different sizes.
+ *
+ * Note: introspection cannot handle this functions parameter mix.
+ *
+ * Returns: (transfer full) (nullable): Error value.
  */
 GnmValue *
 collect_float_pairs (GnmValue const *vx, GnmValue const *vy,
@@ -866,14 +876,20 @@ collect_float_pairs (GnmValue const *vx, GnmValue const *vy,
 
 /**
  * float_range_function2d:
- * @val0:
- * @val1:
- * @ei:
- * @func: (scope call):
- * @flags:
- * @func_error:
+ * @val0: First range
+ * @val1: Second range
+ * @ei: #GnmFuncEvalInfo describing evaluation context
+ * @func: (scope call): implementation function
+ * @flags: #CollectFlags flags describing the collection and interpretation
+ * of values from @val0 and @val1.
+ * @func_error: A #GnmStdError to use to @func indicates an error.
+ * @data: user data for @func
  *
- * Returns: (transfer full):
+ * This implements a Gnumeric sheet function that operates on a matched
+ * pair of ranges.  This function collects the arguments and uses @func to do
+ * the actual computation.
+ *
+ * Returns: (transfer full): Function result or error value.
  **/
 GnmValue *
 float_range_function2d (GnmValue const *val0, GnmValue const *val1,
@@ -911,14 +927,19 @@ float_range_function2d (GnmValue const *val0, GnmValue const *val1,
 
 /**
  * float_range_function2:
- * @val0:
- * @val1:
- * @ei:
- * @func: (scope call):
- * @flags:
- * @func_error:
+ * @val0: First range
+ * @val1: Second range
+ * @ei: #GnmFuncEvalInfo describing evaluation context
+ * @func: (scope call): implementation function
+ * @flags: #CollectFlags flags describing the collection and interpretation
+ * of values from @val0 and @val1.
+ * @func_error: A #GnmStdError to use to @func indicates an error.
+ *
+ * This implements a Gnumeric sheet function that operates on a matched
+ * pair of ranges.  This function collects the arguments and uses @func to do
+ * the actual computation.
  *
- * Returns: (transfer full):
+ * Returns: (transfer full): Function result or error value.
  **/
 GnmValue *
 float_range_function2 (GnmValue const *val0, GnmValue const *val1,
@@ -970,21 +991,20 @@ collect_strings_free (GPtrArray *data)
        g_ptr_array_free (data, TRUE);
 }
 
-/*
+/**
  * collect_strings:
+ * @argc: number of arguments
+ * @argv: (in) (array length=argc): function arguments
+ * @ep: Evaluation position
+ * @flags: #CollectFlags flags describing the collection and interpretation
+ * of values from @argv.
+ * @error: (out): Error return value
  *
- * exprlist:       List of expressions to evaluate.
- * ep:             Current location (for resolving relative cells).
- * flags:          0 or COLLECT_IGNORE_BLANKS
- *
- * Return value:
- *   NULL in case of error, error will be set
- *   Non-NULL in case of success.
- *
- * Evaluate a list of expressions and return the result as a GPtrArray of
+ * Evaluate a list of expressions and return the result as a #GPtrArray of
  * strings.
+ *
+ * Returns: (transfer full) (nullable) (element-type utf8): array of strings.
  */
-
 static GPtrArray *
 collect_strings (int argc, GnmExprConstPtr const *argv,
                 GnmEvalPos const *ep, CollectFlags flags,
@@ -1023,14 +1043,19 @@ collect_strings (int argc, GnmExprConstPtr const *argv,
 
 /**
  * string_range_function:
- * @argc:
- * @argv:
- * @ei:
- * @func: (scope call):
- * @flags:
- * @func_error:
+ * @argc: number of arguments
+ * @argv: (in) (array length=argc): function arguments
+ * @ei: #GnmFuncEvalInfo describing evaluation context
+ * @func: (scope call): implementation function
+ * @flags: #CollectFlags flags describing the collection and interpretation
+ * of values from @argv.
+ * @func_error: A #GnmStdError to use to @func indicates an error.
+ *
+ * This implements a Gnumeric sheet function that operates on a list of
+ * strings.  This function collects the arguments and uses @func to do
+ * the actual computation.
  *
- * Returns: (transfer full):
+ * Returns: (transfer full): Function result or error value.
  **/
 GnmValue *
 string_range_function (int argc, GnmExprConstPtr const *argv,
diff --git a/src/collect.h b/src/collect.h
index 17f68d2..8c276e2 100644
--- a/src/collect.h
+++ b/src/collect.h
@@ -81,7 +81,7 @@ GnmValue *string_range_function (int argc, GnmExprConstPtr const *argv,
 
 GSList *gnm_slist_sort_merge (GSList * list_1, GSList * list_2);
 
-void gnm_strip_missing (gnm_float* data, int *p, GSList *missing);
+void gnm_strip_missing (gnm_float* data, int *n, GSList *missing);
 
 
 G_END_DECLS
diff --git a/src/expr-name.c b/src/expr-name.c
index 593ed42..a2da760 100644
--- a/src/expr-name.c
+++ b/src/expr-name.c
@@ -76,7 +76,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)
@@ -203,7 +203,7 @@ struct _GnmNamedExprCollection {
 /**
  * gnm_named_expr_collection_new:
  *
- * Returns: (transfer full): the newly allocated #GnmNamedExprCollection/
+ * Returns: (transfer full): the newly allocated #GnmNamedExprCollection.
  **/
 GnmNamedExprCollection *
 gnm_named_expr_collection_new (void)
@@ -560,10 +560,11 @@ expr_name_handle_references (GnmNamedExpr *nexpr, gboolean add)
 
 /**
  * expr_name_lookup:
- * @pos:
- * @name:
+ * @pos: #GnmParsePos identifying a #Sheet or a #Workbook.
+ * @name: name of #GnmNamedExpr to look up.
  *
- * lookup but do not reference a named expression.
+ * Return: (transfer none) (nullable): #GnmNamedExpr named @name in the scope
+ * given by @pos; %NULL if no such #GnmNamedExpr exists.
  */
 GnmNamedExpr *
 expr_name_lookup (GnmParsePos const *pp, char const *name)
@@ -646,9 +647,16 @@ cb_name_loop_check (GnmExpr const *expr, GnmExprWalk *data)
        return NULL;
 }
 
-/*
- * NB. if we already have a circular reference in addition
- * to this one we are checking we will come to serious grief.
+/**
+ * expr_name_check_for_loop:
+ * @name: tentative name
+ * @texpr: tentative expression
+ *
+ * Returns: %TRUE if defining the tentative name would cause a circular
+ * name reference.
+ *
+ * NOTE: if we already have a circular reference beforehand, we will come
+ * to serious grief.
  */
 gboolean
 expr_name_check_for_loop (char const *name, GnmExprTop const *texpr)
@@ -840,7 +848,7 @@ gnm_named_expr_get_type (void)
 }
 
 /**
- * expr_name_remove :
+ * expr_name_remove:
  * @nexpr:
  *
  * Remove a @nexpr from its container and deactivate it.
@@ -872,7 +880,7 @@ expr_name_name (GnmNamedExpr const *nexpr)
 }
 
 /**
- * expr_name_set_name :
+ * expr_name_set_name:
  * @nexpr: the named expression
  * @new_name: the new name of the expression
  *
@@ -927,11 +935,12 @@ expr_name_set_name (GnmNamedExpr *nexpr,
 
 
 /**
- * expr_name_as_string :
- * @nexpr:
- * @pp: optionally null.
+ * expr_name_as_string:
+ * @nexpr: A #GnmNamedExpr
+ * @pp: (nullable): Position where name was defined.
+ * @fmt: #GnmConventions describing how to render @nexpr
  *
- * returns a string that the caller needs to free.
+ * Returns: (transfer full): The rendering of @nexpr given convention @fmt.
  */
 char *
 expr_name_as_string (GnmNamedExpr const *nexpr, GnmParsePos const *pp,
@@ -942,6 +951,14 @@ expr_name_as_string (GnmNamedExpr const *nexpr, GnmParsePos const *pp,
        return gnm_expr_top_as_string (nexpr->texpr, pp, fmt);
 }
 
+/**
+ * expr_name_eval:
+ * @nexpr: A #GnmNamedExpr
+ * @pos: Position where evaluation takes place
+ * @flags: #GnmExprEvalFlags flags describing context.
+ *
+ * Returns: (transfer full): The resulting value.
+ */
 GnmValue *
 expr_name_eval (GnmNamedExpr const *nexpr, GnmEvalPos const *pos,
                GnmExprEvalFlags flags)
@@ -1014,11 +1031,11 @@ expr_name_set_pos (GnmNamedExpr *nexpr, GnmParsePos const *pp)
 }
 
 /**
- * expr_name_set_expr :
- * @nexpr: the named expression
- * @texpr: the new content
+ * expr_name_set_expr:
+ * @nexpr: #GnmNamedExpr to change
+ * @texpr: (transfer full) (nullable): the new contents
  *
- * Unrefs the current content of @nexpr and absorbs a ref to @new_expr.
+ * Set the content of @nexpr to @texpr.
  **/
 void
 expr_name_set_expr (GnmNamedExpr *nexpr, GnmExprTop const *texpr)
@@ -1084,7 +1101,7 @@ expr_name_remove_dep (GnmNamedExpr *nexpr, GnmDependent *dep)
 }
 
 /**
- * expr_name_is_placeholder :
+ * expr_name_is_placeholder:
  * @ne:
  *
  * Returns TRUE if @ne is a placeholder for an unknown name
@@ -1147,7 +1164,7 @@ cb_expr_name_in_use (G_GNUC_UNUSED gconstpointer key,
 }
 
 /**
- * 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
@@ -1201,11 +1218,13 @@ expr_name_cmp_by_name (GnmNamedExpr const *a, GnmNamedExpr const *b)
 }
 
 /**
- * sheet_names_check :
- * @sheet:
- * @r:
+ * sheet_names_check:
+ * @sheet: #Sheet
+ * @r: #GnmRange
+ *
+ * Returns: (transfer none) (nullable): The name of a #GnmNamedExpr if
+ * @sheet!@r is the target of a named range.
  *
- * Returns 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-name.h b/src/expr-name.h
index ffb765f..d7e2ef0 100644
--- a/src/expr-name.h
+++ b/src/expr-name.h
@@ -37,7 +37,8 @@ void expr_name_perm_add        (Sheet *sheet,
 GnmNamedExpr *expr_name_ref   (GnmNamedExpr *nexpr);
 void    expr_name_unref      (GnmNamedExpr *nexpr);
 void     expr_name_remove     (GnmNamedExpr *nexpr);
-GnmValue*expr_name_eval       (GnmNamedExpr const *ne, GnmEvalPos const *ep,
+GnmValue*expr_name_eval       (GnmNamedExpr const *nexpr,
+                              GnmEvalPos const *pos,
                               GnmExprEvalFlags flags);
 
 const char *expr_name_name    (GnmNamedExpr const *nexpr);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]