[gnome-calculator] GCalc: Removed MathSolver. Add interfaces documentation.

[Daniel Espinosa Ortiz <despinosa src gnome org>]

commit b51699bfbd0be94779d2ab06f5ac3bd9837d7d21
Author: Daniel Espinosa <esodan gmail com>
Date:   Thu Oct 17 13:35:32 2019 -0500

    GCalc: Removed MathSolver. Add interfaces documentation.

 gcalc/gcalc-hashable.vala              |  8 +++++++
 gcalc/gcalc-math-equation-manager.vala | 35 +++++++++++++++++++++++++++++
 gcalc/gcalc-math-equation.vala         |  6 +++++
 gcalc/gcalc-math-expression.vala       |  3 +++
 gcalc/gcalc-math-pow.vala              |  3 +++
 gcalc/gcalc-math-result.vala           |  3 +++
 gcalc/gcalc-math-solver.vala           | 31 --------------------------
 gcalc/gcalc-math-term.vala             | 14 ++++++++++++
 gcalc/gcalc-solver.vala                | 40 ++++++++++++++++++++++++++++++----
 gcalc/meson.build                      |  1 -
 10 files changed, 108 insertions(+), 36 deletions(-)
---
diff --git a/gcalc/gcalc-hashable.vala b/gcalc/gcalc-hashable.vala
index 9d147607..48d1837f 100644
--- a/gcalc/gcalc-hashable.vala
+++ b/gcalc/gcalc-hashable.vala
@@ -18,7 +18,15 @@
  * Authors:
  *      Daniel Espinosa <esodan gmail com>
  */
+/**
+ * Implemented by objects able to produce a hash.
+ *
+ * Returned value can be used in hash tables, for example.
+ */
 public interface GCalc.Hashable : Object {
+  /**
+   * Calculates the hash for this
+   */
   public abstract uint hash ();
 }
 
diff --git a/gcalc/gcalc-math-equation-manager.vala b/gcalc/gcalc-math-equation-manager.vala
index 5a415b10..47810dd6 100644
--- a/gcalc/gcalc-math-equation-manager.vala
+++ b/gcalc/gcalc-math-equation-manager.vala
@@ -18,6 +18,41 @@
  * Authors:
  *      Daniel Espinosa <esodan gmail com>
  */
+/**
+ * Equation manager, holding a set of equations and variables.
+ *
+ * Equations can depend on calculated expression from variables or
+ * values set to variables when they are a {@link MathParameter}
+ *
+ * In the next code you create a parser, then use {@link Parser.parse}
+ * to add the parsed equation to an equation manager.
+ * {{{
+ *  var parser = new Parser ();
+ *  var eqman = new EquationManager ();
+ *  parser.parse ("3*5", eqman);
+ *  var eq = eqman.equations.get_item (0) as MathEquation;
+ *  var res = eq.solve ();
+ *  var c = (MathConstant) res;
+ *  // Result will be 15
+ *  stdout.printf ("%g", c.real ());
+ * }}}
+ *
+ * Is possible to create expressions, set to a variable, add to an equation manager
+ * create an expression using that variable to add to the manager; then solve the
+ * dependant equation and then the variable will be evalated too, in order to produce
+ * a result:
+ * {{{
+ *  var parser = new Parser ();
+ *  var eqman = new EquationManager ();
+ *  parser.parse ("x=3*5", eqman);
+ *  parser.parse ("2*x+7*x^2", eqman);
+ *  var eq = eqman.equations.get_item (1) as MathEquation;
+ *  var res = eq.solve ();
+ *  var c = (MathConstant) res;
+ *  // Result will be 1605
+ *  stdout.printf ("%g", c.real ());
+ * }}}
+ */
 public interface GCalc.MathEquationManager : Object {
   public abstract ExpressionContainer equations { get; }
   public abstract ExpressionContainer functions { get; }
diff --git a/gcalc/gcalc-math-equation.vala b/gcalc/gcalc-math-equation.vala
index a89ad46f..a45a9095 100644
--- a/gcalc/gcalc-math-equation.vala
+++ b/gcalc/gcalc-math-equation.vala
@@ -18,7 +18,13 @@
  * Authors:
  *      Daniel Espinosa <esodan gmail com>
  */
+/**
+ * A math equation with multiple terms
+ */
 public interface GCalc.MathEquation : Object, MathExpression {
+  /**
+   * Set of variables present in the equation expression
+   */
   public abstract ExpressionHashMap variables { get; }
 }
 
diff --git a/gcalc/gcalc-math-expression.vala b/gcalc/gcalc-math-expression.vala
index 988ad31e..bbcc76d2 100644
--- a/gcalc/gcalc-math-expression.vala
+++ b/gcalc/gcalc-math-expression.vala
@@ -40,6 +40,9 @@ public interface GCalc.MathExpression : Object {
   public abstract MathResult solve ();
 }
 
+/**
+ * Represent an expression in error condition
+ */
 public interface GCalc.ErrorExpression : Object, MathExpression {
 }
 
diff --git a/gcalc/gcalc-math-pow.vala b/gcalc/gcalc-math-pow.vala
index a043ca39..7fdfbfbb 100644
--- a/gcalc/gcalc-math-pow.vala
+++ b/gcalc/gcalc-math-pow.vala
@@ -18,5 +18,8 @@
  * Authors:
  *      Daniel Espinosa <esodan gmail com>
  */
+/**
+ * A pow operator in a math expression
+ */
 public interface GCalc.MathPow : Object, MathExpression, MathOperator {}
 
diff --git a/gcalc/gcalc-math-result.vala b/gcalc/gcalc-math-result.vala
index d76832f1..7b2c8234 100644
--- a/gcalc/gcalc-math-result.vala
+++ b/gcalc/gcalc-math-result.vala
@@ -18,6 +18,9 @@
  * Authors:
  *      Daniel Espinosa <esodan gmail com>
  */
+/**
+ * A result of a calculation when the expression is solved
+ */
 public interface GCalc.MathResult : Object {
   public abstract string to_string ();
   public abstract MathExpression expression { get; }
diff --git a/gcalc/gcalc-math-term.vala b/gcalc/gcalc-math-term.vala
index 8e5c6a19..b29d14b4 100644
--- a/gcalc/gcalc-math-term.vala
+++ b/gcalc/gcalc-math-term.vala
@@ -18,7 +18,15 @@
  * Authors:
  *      Daniel Espinosa <esodan gmail com>
  */
+/**
+ * A term in a math expression.
+ *
+ * Is a container of other terms.
+ */
 public interface GCalc.MathTerm : Object, MathExpression {
+  /**
+   * Add a child term
+   */
   public virtual MathExpression add (MathTerm t) throws GLib.Error {
     if (t.expressions.get_n_items () == 0) {
       return new Constant.@double (1.0);
@@ -31,6 +39,9 @@ public interface GCalc.MathTerm : Object, MathExpression {
     }
     return res;
   }
+  /**
+   * Evaluates the term an returns the resulting {@link MathExpression}
+   */
   public virtual MathExpression evaluate () throws GLib.Error {
     MathExpression current = null;
     MathOperator current_operator = null;
@@ -93,6 +104,9 @@ public interface GCalc.MathTerm : Object, MathExpression {
     }
     return current;
   }
+  /**
+   * Take two {@link MathConstant} and evaluate them using the given {@link MathOperator}
+   */
   public static MathExpression evaluate_constants (MathConstant c1, MathConstant c2, MathOperator op)
     throws GLib.Error
   {
diff --git a/gcalc/gcalc-solver.vala b/gcalc/gcalc-solver.vala
index 7866af8f..51f70aeb 100644
--- a/gcalc/gcalc-solver.vala
+++ b/gcalc/gcalc-solver.vala
@@ -19,14 +19,42 @@
  *      Daniel Espinosa <esodan gmail com>
  */
 using GCalc;
+/**
+ * Math expression solver.
+ *
+ * Add any required equations to {@link equation_manager} or use {@link add_expression},
+ * then {@link solve} will add a new equation and returns the resulting
+ * {@link MathResult}.
+ * {{{
+ *  var s = new Solver ();
+ *  s.add ("x=3*5");
+ *  var res = s.solve ("2*x+7*x^2");
+ *  var c = (MathConstant) res;
+ *  // Result will be 1605
+ *  stdout.printf ("%g", c.real ());
+ * }}}
+ */
+public class GCalc.Solver : Object {
+  /**
+   * An equation manager using to solve a given expression
+   */
+  public MathEquationManager equation_manager { get; set; }
 
-public class GCalc.Solver : Object, MathSolver {
   construct {
     equation_manager = new EquationManager ();
   }
-  // Sover
-  internal MathEquationManager equation_manager { get; set; }
-  internal MathResult solve (string str) throws GLib.Error {
+
+  /**
+   * Add an equation to {@link equation_manager}
+   */
+  public void add_expression (string exp) throws GLib.Error {
+      var p = new Parser ();
+      p.parse (exp, equation_manager);
+  }
+  /**
+   * Add an equation to {@link equation_manager} and solves it
+   */
+  public MathResult solve (string str) throws GLib.Error {
     var p = new Parser ();
     MathResult res;
     try {
@@ -45,3 +73,7 @@ public class GCalc.Solver : Object, MathSolver {
     return res;
   }
 }
+
+public errordomain GCalc.SolverError {
+  EXPRESSION_ERROR
+}
diff --git a/gcalc/meson.build b/gcalc/meson.build
index a5aab9ff..dcfc78b8 100644
--- a/gcalc/meson.build
+++ b/gcalc/meson.build
@@ -101,7 +101,6 @@ gcalc_sources = files([
        'gcalc-math-polynomial.vala',
        'gcalc-math-pow.vala',
        'gcalc-math-result.vala',
-       'gcalc-math-solver.vala',
        'gcalc-math-term.vala',
        'gcalc-math-variable.vala',
        'gcalc-minus.vala',