[gnumeric] Introspection fixes

[Morten Welinder <mortenw src gnome org>]

commit cfe86185ffeaa112e40c8550f6682316b91d8c63
Author: Morten Welinder <terra gnome org>
Date:   Sun May 13 22:17:06 2018 -0400

    Introspection fixes

 src/Makefile.am        |    2 +
 src/style-conditions.c |   16 ++++--
 src/tools/gnm-solver.c |  132 +++++++++++++++++++++++++++++++++++++++++++++---
 src/tools/gnm-solver.h |   26 +++++----
 src/validation.c       |   27 +++++++---
 5 files changed, 171 insertions(+), 32 deletions(-)
---
diff --git a/src/Makefile.am b/src/Makefile.am
index 3170dc5..47b2500 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -545,6 +545,8 @@ Gnm_@GNUMERIC_API_VER_@_gir_FILES = \
        tools/dao.h \
        tools/scenarios.c \
        tools/scenarios.h \
+       tools/gnm-solver.c \
+       tools/gnm-solver.h \
        tools/tools.h \
        widgets/gnumeric-expr-entry.c \
        widgets/gnumeric-expr-entry.h
diff --git a/src/style-conditions.c b/src/style-conditions.c
index e492505..228c7a1 100644
--- a/src/style-conditions.c
+++ b/src/style-conditions.c
@@ -206,6 +206,13 @@ gnm_style_cond_set_sheet (GnmStyleCond *cond, Sheet *sheet)
                dependent_managed_set_sheet (&cond->deps[ui], sheet);
 }
 
+/**
+ * gnm_style_cond_get_expr:
+ * @cond: #GnmStyleCond
+ * @idx: index
+ *
+ * Returns: (transfer none): the #GnmExprTop for the @idx'th condition.
+ **/
 GnmExprTop const *
 gnm_style_cond_get_expr (GnmStyleCond const *cond, unsigned idx)
 {
@@ -706,11 +713,12 @@ GSF_CLASS (GnmStyleConditions, gnm_style_conditions,
 
 /**
  * gnm_style_conditions_new:
+ * @sheet: #Sheet
  *
- * Convenience tool to create a GnmStyleCondition.  Straight g_object_new
+ * Convenience tool to create a #GnmStyleCondition.  Straight g_object_new
  * will work too.
  *
- * Returns a GnmStyleConditions that the caller is responsible for.
+ * Returns: (transfer full): a #GnmStyleConditions
  **/
 GnmStyleConditions  *
 gnm_style_conditions_new (Sheet *sheet)
@@ -725,9 +733,9 @@ gnm_style_conditions_new (Sheet *sheet)
 
 /**
  * gnm_style_conditions_dup:
- * @sc: the #GnmStyleConditions to duplicate.
+ * @sc: (nullable): the #GnmStyleConditions to duplicate.
  *
- * Returns: (transfer full): the duplicated #GnmStyleConditions.
+ * Returns: (transfer full) (nullable): the duplicated #GnmStyleConditions.
  **/
 GnmStyleConditions *
 gnm_style_conditions_dup (GnmStyleConditions const *sc)
diff --git a/src/tools/gnm-solver.c b/src/tools/gnm-solver.c
index 82aa6b3..8647b1c 100644
--- a/src/tools/gnm-solver.c
+++ b/src/tools/gnm-solver.c
@@ -162,6 +162,24 @@ gnm_solver_constraint_dup (GnmSolverConstraint *c, Sheet *sheet)
        return res;
 }
 
+static GnmSolverConstraint *
+gnm_solver_constraint_dup1 (GnmSolverConstraint *c)
+{
+       return gnm_solver_constraint_dup (c, c->lhs.sheet);
+}
+
+GType
+gnm_solver_constraint_get_type (void)
+{
+       static GType t = 0;
+
+       if (t == 0)
+               t = g_boxed_type_register_static ("GnmSolverConstraint",
+                        (GBoxedCopyFunc)gnm_solver_constraint_dup1,
+                        (GBoxedFreeFunc)gnm_solver_constraint_free);
+       return t;
+}
+
 gboolean
 gnm_solver_constraint_equal (GnmSolverConstraint const *a,
                             GnmSolverConstraint const *b)
@@ -246,6 +264,12 @@ gnm_solver_constraint_valid (GnmSolverConstraint const *c,
        return TRUE;
 }
 
+/**
+ * gnm_solver_constraint_get_lhs:
+ * @c: GnmSolverConstraint
+ *
+ * Returns: (transfer none) (nullable): Get left-hand side of constraint @c.
+ */
 GnmValue const *
 gnm_solver_constraint_get_lhs (GnmSolverConstraint const *c)
 {
@@ -253,15 +277,25 @@ gnm_solver_constraint_get_lhs (GnmSolverConstraint const *c)
        return texpr ? gnm_expr_top_get_constant (texpr) : NULL;
 }
 
+/**
+ * gnm_solver_constraint_set_lhs:
+ * @c: GnmSolverConstraint
+ * @v: (transfer full) (nullable): new left-hand side
+ */
 void
 gnm_solver_constraint_set_lhs (GnmSolverConstraint *c, GnmValue *v)
 {
-       /* Takes ownership.  */
        GnmExprTop const *texpr = v ? gnm_expr_top_new_constant (v) : NULL;
        dependent_managed_set_expr (&c->lhs, texpr);
        if (texpr) gnm_expr_top_unref (texpr);
 }
 
+/**
+ * gnm_solver_constraint_get_rhs:
+ * @c: GnmSolverConstraint
+ *
+ * Returns: (transfer none) (nullable): Get right-hand side of constraint @c.
+ */
 GnmValue const *
 gnm_solver_constraint_get_rhs (GnmSolverConstraint const *c)
 {
@@ -269,15 +303,34 @@ gnm_solver_constraint_get_rhs (GnmSolverConstraint const *c)
        return texpr ? gnm_expr_top_get_constant (texpr) : NULL;
 }
 
+/**
+ * gnm_solver_constraint_set_rhs:
+ * @c: GnmSolverConstraint
+ * @v: (transfer full) (nullable): new right-hand side
+ */
 void
 gnm_solver_constraint_set_rhs (GnmSolverConstraint *c, GnmValue *v)
 {
-       /* Takes ownership.  */
        GnmExprTop const *texpr = v ? gnm_expr_top_new_constant (v) : NULL;
        dependent_managed_set_expr (&c->rhs, texpr);
        if (texpr) gnm_expr_top_unref (texpr);
 }
 
+/**
+ * gnm_solver_constraint_get_part:
+ * @c: GnmSolverConstraint
+ * @sp: GnmSolverParameters
+ * @i: part index
+ * @lhs: (optional) (out): #GnmCell of left-hand side
+ * @cl: (optional) (out): constant value of left-hand side
+ * @rhs: (optional) (out): #GnmCell of right-hand side
+ * @cr: (optional) (out): constant value of left-hand side
+ *
+ * This splits @c into parts and returns information about the @i'th part.
+ * There will be multiple parts when the left-hand side is a cell range.
+ *
+ * Returns: %TRUE if the @i'th part exists.
+ */
 gboolean
 gnm_solver_constraint_get_part (GnmSolverConstraint const *c,
                                GnmSolverParameters const *sp, int i,
@@ -454,6 +507,13 @@ gnm_solver_param_new (Sheet *sheet)
                             NULL);
 }
 
+/**
+ * gnm_solver_param_dup:
+ * @src: #GnmSolverParameters
+ * @new_sheet: #Sheet
+ *
+ * Returns: (transfer full): duplicate @src, but for @new_sheet.
+ */
 GnmSolverParameters *
 gnm_solver_param_dup (GnmSolverParameters *src, Sheet *new_sheet)
 {
@@ -518,6 +578,12 @@ gnm_solver_param_equal (GnmSolverParameters const *a,
        return la == lb;
 }
 
+/**
+ * gnm_solver_param_get_input:
+ * @sp: #GnmSolverParameters
+ *
+ * Returns: (transfer none) (nullable): the input cell area.
+ */
 GnmValue const *
 gnm_solver_param_get_input (GnmSolverParameters const *sp)
 {
@@ -526,10 +592,14 @@ gnm_solver_param_get_input (GnmSolverParameters const *sp)
                : NULL;
 }
 
+/**
+ * gnm_solver_param_set_input:
+ * @sp: #GnmSolverParameters
+ * @v: (transfer full) (nullable): new input area
+ */
 void
 gnm_solver_param_set_input (GnmSolverParameters *sp, GnmValue *v)
 {
-       /* Takes ownership.  */
        GnmExprTop const *texpr = v ? gnm_expr_top_new_constant (v) : NULL;
        dependent_managed_set_expr (&sp->input, texpr);
        if (texpr) gnm_expr_top_unref (texpr);
@@ -548,6 +618,12 @@ cb_grab_cells (GnmCellIter const *iter, gpointer user)
        return NULL;
 }
 
+/**
+ * gnm_solver_param_get_input_cells:
+ * @sp: #GnmSolverParameters
+ *
+ * Returns: (element-type GnmCell) (transfer container):
+ */
 GPtrArray *
 gnm_solver_param_get_input_cells (GnmSolverParameters const *sp)
 {
@@ -968,7 +1044,7 @@ gnm_solver_set_property (GObject *object, guint property_id,
 }
 
 /**
- * gnm_solver_prepare:
+ * gnm_solver_prepare: (virtual prepare)
  * @sol: solver
  * @wbc: control for user interaction
  * @err: location to store error
@@ -992,7 +1068,7 @@ gnm_solver_prepare (GnmSolver *sol, WorkbookControl *wbc, GError **err)
 }
 
 /**
- * gnm_solver_start:
+ * gnm_solver_start: (virtual start)
  * @sol: solver
  * @wbc: control for user interaction
  * @err: location to store error
@@ -1023,7 +1099,7 @@ gnm_solver_start (GnmSolver *sol, WorkbookControl *wbc, GError **err)
 }
 
 /**
- * gnm_solver_stop:
+ * gnm_solver_stop: (virtual stop)
  * @sol: solver
  * @err: location to store error
  *
@@ -1885,7 +1961,7 @@ gnm_solver_create_report (GnmSolver *solver, const char *base)
 
 /**
  * gnm_solver_get_target_value:
- * @isol: solver
+ * @solver: solver
  *
  * Returns: the current value of the target cell, possibly with the sign
  * flipped.
@@ -1929,6 +2005,12 @@ gnm_solver_set_vars (GnmSolver *sol, gnm_float const *xs)
                gnm_solver_set_var (sol, i, xs[i]);
 }
 
+/**
+ * gnm_solver_save_vars:
+ * @sol: #GnmSolver
+ *
+ * Returns: (transfer full) (element-type GnmValue):
+ */
 GPtrArray *
 gnm_solver_save_vars (GnmSolver *sol)
 {
@@ -1943,6 +2025,11 @@ gnm_solver_save_vars (GnmSolver *sol)
        return vals;
 }
 
+/**
+ * gnm_solver_restore_vars:
+ * @sol: #GnmSolver
+ * @vals: (transfer full) (element-type GnmValue): values to restore
+ */
 void
 gnm_solver_restore_vars (GnmSolver *sol, GPtrArray *vals)
 {
@@ -2135,7 +2222,7 @@ gnm_solver_has_analytic_hessian (GnmSolver *sol)
 }
 
 /**
- * gnm_solver_compute_hessian:
+ * gnm_solver_compute_hessian: (skip)
  * @sol: Solver
  * @xs: Point to compute Hessian at
  *
@@ -2900,6 +2987,9 @@ cb_child_exit (G_GNUC_UNUSED GPid pid, gint status, GnmSubSolver *subsol)
        }
 }
 
+/**
+ * gnm_sub_solver_spawn: (skip)
+ */
 gboolean
 gnm_sub_solver_spawn (GnmSubSolver *subsol,
                      char **argv,
@@ -3183,6 +3273,9 @@ gnm_solver_iterator_iterate (GnmSolverIterator *iter)
        return progress;
 }
 
+/**
+ * gnm_solver_iterator_new_func: (skip)
+ */
 GnmSolverIterator *
 gnm_solver_iterator_new_func (GCallback iterate, gpointer user)
 {
@@ -3661,12 +3754,28 @@ GSF_CLASS (GnmSolverFactory, gnm_solver_factory,
 
 static GSList *solvers;
 
+/**
+ * gnm_solver_db_get:
+ *
+ * Returns: (transfer none) (element-type GnmSolverFactory): list of
+ * registered solver factories.
+ */
 GSList *
 gnm_solver_db_get (void)
 {
        return solvers;
 }
 
+/**
+ * gnm_solver_factory_new: (skip)
+ * @id:
+ * @name:
+ * @type:
+ * @creator: xxx(scope forever)
+ * @functional: xxx(scope forever)
+ *
+ * Returns: (transfer full): a new #GnmSolverFactory
+ */
 GnmSolverFactory *
 gnm_solver_factory_new (const char *id,
                        const char *name,
@@ -3689,6 +3798,13 @@ gnm_solver_factory_new (const char *id,
        return res;
 }
 
+/**
+ * gnm_solver_factory_create:
+ * @factory: #GnmSolverFactory
+ * @param: #GnmSolverParameters
+ *
+ * Returns: (transfer full): a new #GnmSolver
+ */
 GnmSolver *
 gnm_solver_factory_create (GnmSolverFactory *factory,
                           GnmSolverParameters *param)
diff --git a/src/tools/gnm-solver.h b/src/tools/gnm-solver.h
index 7f33146..621468a 100644
--- a/src/tools/gnm-solver.h
+++ b/src/tools/gnm-solver.h
@@ -67,6 +67,8 @@ struct GnmSolverConstraint_ {
        GnmDependent rhs;
 };
 
+GType gnm_solver_constraint_get_type (void);
+
 GnmSolverConstraint *gnm_solver_constraint_new (Sheet *sheet);
 void gnm_solver_constraint_free (GnmSolverConstraint *c);
 GnmSolverConstraint *gnm_solver_constraint_dup (GnmSolverConstraint *c,
@@ -145,7 +147,7 @@ GType gnm_solver_param_get_type (void);
 GnmSolverParameters *gnm_solver_param_new (Sheet *sheet);
 
 /* Duplicate a GnmSolverParameters object. */
-GnmSolverParameters *gnm_solver_param_dup (GnmSolverParameters *src_param,
+GnmSolverParameters *gnm_solver_param_dup (GnmSolverParameters *src,
                                           Sheet *new_sheet);
 
 gboolean gnm_solver_param_equal (GnmSolverParameters const *a,
@@ -256,20 +258,20 @@ struct GnmSolver_ {
 typedef struct {
        GObjectClass parent_class;
 
-       gboolean (*prepare) (GnmSolver *solver,
+       gboolean (*prepare) (GnmSolver *sol,
                             WorkbookControl *wbc, GError **err);
-       gboolean (*start) (GnmSolver *solver,
+       gboolean (*start) (GnmSolver *sol,
                           WorkbookControl *wbc, GError **err);
-       gboolean (*stop) (GnmSolver *solver, GError **err);
+       gboolean (*stop) (GnmSolver *sol, GError **err);
 } GnmSolverClass;
 
 GType gnm_solver_get_type (void);
 
-gboolean gnm_solver_prepare (GnmSolver *solver,
+gboolean gnm_solver_prepare (GnmSolver *sol,
                             WorkbookControl *wbc, GError **err);
-gboolean gnm_solver_start (GnmSolver *solver,
+gboolean gnm_solver_start (GnmSolver *sol,
                           WorkbookControl *wbc, GError **err);
-gboolean gnm_solver_stop (GnmSolver *solver, GError **err);
+gboolean gnm_solver_stop (GnmSolver *sol, GError **err);
 
 void gnm_solver_set_status (GnmSolver *solver, GnmSolverStatus status);
 
@@ -481,10 +483,10 @@ void gnm_iter_solver_set_solution (GnmIterSolver *isol);
 #define GNM_SOLVER_FACTORY(o)          (G_TYPE_CHECK_INSTANCE_CAST ((o), GNM_SOLVER_FACTORY_TYPE, 
GnmSolverFactory))
 #define GNM_IS_SOLVER_FACTORY(o)       (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNM_SOLVER_FACTORY_TYPE))
 
-typedef GnmSolver * (*GnmSolverCreator) (GnmSolverFactory *,
-                                        GnmSolverParameters *);
-typedef gboolean (*GnmSolverFactoryFunctional) (GnmSolverFactory *,
-                                               WBCGtk *);
+typedef GnmSolver * (*GnmSolverCreator) (GnmSolverFactory *factory,
+                                        GnmSolverParameters *param);
+typedef gboolean (*GnmSolverFactoryFunctional) (GnmSolverFactory *factory,
+                                               WBCGtk *wbcg);
 
 struct GnmSolverFactory_ {
        GObject parent;
@@ -506,7 +508,7 @@ GnmSolverFactory *gnm_solver_factory_new (const char *id,
                                          const char *name,
                                          GnmSolverModelType type,
                                          GnmSolverCreator creator,
-                                         GnmSolverFactoryFunctional funct);
+                                         GnmSolverFactoryFunctional functional);
 GnmSolver *gnm_solver_factory_create (GnmSolverFactory *factory,
                                      GnmSolverParameters *param);
 gboolean gnm_solver_factory_functional (GnmSolverFactory *factory,
diff --git a/src/validation.c b/src/validation.c
index 781eec7..894a4eb 100644
--- a/src/validation.c
+++ b/src/validation.c
@@ -231,16 +231,22 @@ gnm_validation_op_get_type (void)
 
 /**
  * gnm_validation_new:
+ * @style: #ValidationStyle
+ * @op: #ValidationOp
+ * @sheet: #Sheet
  * @title: will be copied.
  * @msg: will be copied.
- * @texpr0: absorb the reference to the expression (optionally %NULL).
- * @texpr1: absorb the reference to the expression (optionally %NULL).
+ * @texpr0: (transfer full) (nullable): first expression
+ * @texpr1: (transfer full) (nullable): second expression
+ * @allow_blank:
+ * @use_dropdown:
  *
  * Does _NOT_ require all necessary information to be set here.
  * gnm_validation_set_expr can be used to change the expressions after creation,
- * and gnm_validation_is_ok can be used to ensure that things are properly setup.
+ * and gnm_validation_is_ok can be used to ensure that things are properly
+ * setup.
  *
- * Returns a new @GnmValidation object that needs to be unrefed.
+ * Returns: (transfer full): a new @GnmValidation object
  **/
 GnmValidation *
 gnm_validation_new (ValidationStyle style,
@@ -515,12 +521,16 @@ cb_validate_custom (GnmValueIter const *v_iter, GnmValue const *target)
  * @wbc:
  * @mstyle:
  * @sheet:
+ * @pos:
+ * @showed_dialog: (out) (optional):
  *
- * validation set in the GnmStyle if applicable.
+ * Checks the validation in @mstyle, if any.  Set @showed_dialog to %TRUE
+ * if a dialog was showed as a result.
  **/
 ValidationStatus
 gnm_validation_eval (WorkbookControl *wbc, GnmStyle const *mstyle,
-                Sheet *sheet, GnmCellPos const *pos, gboolean *showed_dialog)
+                    Sheet *sheet, GnmCellPos const *pos,
+                    gboolean *showed_dialog)
 {
        GnmValidation const *v;
        GnmCell *cell;
@@ -731,8 +741,9 @@ validation_eval_range_cb (GnmCellIter const *iter, validation_eval_t *closure)
 
 ValidationStatus
 gnm_validation_eval_range (WorkbookControl *wbc,
-                      Sheet *sheet, GnmCellPos const *pos, GnmRange const *r,
-                      gboolean *showed_dialog)
+                          Sheet *sheet, GnmCellPos const *pos,
+                          GnmRange const *r,
+                          gboolean *showed_dialog)
 {
        GnmValue *result;
        validation_eval_t closure;