test: In doc test, ignore comment-only lines that don't say "returns/throws"

  Plus knock-on changes. This "simple" change unsurprisingly altered what
  doc tests occurred, leading to shaking out a bug in doc testing,
  which in turn shook out a bug in logical `and` (!).
  All should be well now.

  Also prevent `numeric(blah, 'bigint')` from throwing when it
  needs to round.

Author: gwhitney

src/core/function/import.js

@@ -45,7 +45,7 @@ export function importFactory (typed, load, math, importedFactories) {
    *        return 'hello, ' + name + '!'
    *      }
    *    })
-   *        // use the imported function and variable
+   *    // use the imported function and variable
    *    math.myvalue * 2               // 84
    *
    *    math.hello('user')             // 'hello, user!'

src/function/algebra/polynomialRoot.js

@@ -42,17 +42,18 @@ export const createPolynomialRoot = /* #__PURE__ */ factory(name, dependencies,
    *     math.polynomialRoot(constant, linearCoeff, quadraticCoeff, cubicCoeff)
    *
    * Examples:
-   *         // linear
+   *     // linear
    *     math.polynomialRoot(6, 3)                                        // [-2]
    *     math.polynomialRoot(math.complex(6,3), 3)                        // [-2 - i]
    *     math.polynomialRoot(math.complex(6,3), math.complex(2,1))        // [-3 + 0i]
-   *         // quadratic
+   *     // quadratic
    *     math.polynomialRoot(2, -3, 1)                                    // [2, 1]
    *     math.polynomialRoot(8, 8, 2)                                     // [-2]
    *     math.polynomialRoot(-2, 0, 1)                                    // [1.4142135623730951, -1.4142135623730951]
    *     math.polynomialRoot(2, -2, 1)                                    // [1 + i, 1 - i]
    *     math.polynomialRoot(math.complex(1,3), math.complex(-3, -2), 1)  // [2 + i, 1 + i]
-   *         // cubic
+   *
+   *     // cubic
    *     math.polynomialRoot(-6, 11, -6, 1)                               // [1, 3, 2]
    *     math.polynomialRoot(-8, 0, 0, 1)                                 // [-1 - 1.7320508075688774i, 2, -1 + 1.7320508075688774i]
    *     math.polynomialRoot(0, 8, 8, 2)                                  // [0, -2]

src/function/algebra/rationalize.js

@@ -75,24 +75,24 @@ export const createRationalize = /* #__PURE__ */ factory(name, dependencies, ({
    * Examples:
    *
    *     math.rationalize('sin(x)+y')
-   *                   //  Error: There is an unsolved function call
-   *     math.rationalize('2x/y - y/(x+1)')
-   *                   // (2*x^2-y^2+2*x)/(x*y+y)
-   *     math.rationalize('(2x+1)^6')
-   *                   // 64*x^6+192*x^5+240*x^4+160*x^3+60*x^2+12*x+1
+   *                   // throws Error: There is an unsolved function call
+   *     math.rationalize('2x/y - y/(x+1)') // (2*x^2-y^2+2*x)/(x*y+y)
+   *     // math.rationalize('(2x+1)^6') // hangs, see #3351
+   *     // returns 64*x^6+192*x^5+240*x^4+160*x^3+60*x^2+12*x+1
    *     math.rationalize('2x/( (2x-1) / (3x+2) ) - 5x/ ( (3x+4) / (2x^2-5) ) + 3')
-   *                   // -20*x^4+28*x^3+104*x^2+6*x-12)/(6*x^2+5*x-4)
-   *     math.rationalize('x/(1-x)/(x-2)/(x-3)/(x-4) + 2x/ ( (1-2x)/(2-3x) )/ ((3-4x)/(4-5x) )') =
-   *                   // (-30*x^7+344*x^6-1506*x^5+3200*x^4-3472*x^3+1846*x^2-381*x)/
-   *                   //     (-8*x^6+90*x^5-383*x^4+780*x^3-797*x^2+390*x-72)
+   *                   // returns -20*x^4+28*x^3+104*x^2+6*x-12)/(6*x^2+5*x-4)
+   *     // math.rationalize('x/(1-x)/(x-2)/(x-3)/(x-4) + 2x/ ( (1-2x)/(2-3x) )/ ((3-4x)/(4-5x) )') // hangs, see #3351
+   *     // returns (-30*x^7+344*x^6-1506*x^5+3200*x^4-3472*x^3+1846*x^2-381*x)/(-8*x^6+90*x^5-383*x^4+780*x^3-797*x^2+390*x-72)
    *
    *     math.rationalize('x+x+x+y',{y:1}) // 3*x+1
    *     math.rationalize('x+x+x+y',{})    // 3*x+y
    *
-   *     const ret = math.rationalize('x+x+x+y',{},true)
-   *                   // ret.expression=3*x+y, ret.variables = ["x","y"]
-   *     const ret = math.rationalize('-2+5x^2',{},true)
-   *                   // ret.expression=5*x^2-2, ret.variables = ["x"], ret.coefficients=[-2,0,5]
+   *     const r = math.rationalize('x+x+x+y',{},true);
+   *     [r.expression.toString(), r.variables] // ['3 * x + y', ['x', 'y']]
+   *
+   *     const ret = math.rationalize('-2+5x^2',{},true);
+   *     [ret.expression.toString(), ret.variables, ret.coefficients]
+   *                   // returns ['5 * x ^ 2 - 2', ['x'], [-2,0,5]]
    *
    * See also:
    *

src/function/algebra/solver/lsolve.js

@@ -28,7 +28,7 @@ export const createLsolve = /* #__PURE__ */ factory(name, dependencies, ({ typed
    *
    *    const a = [[-2, 3], [2, 1]]
    *    const b = [11, 9]
-   *    const x = lsolve(a, b)  // [[-5.5], [20]]
+   *    math.lsolve(a, b)  // [[-5.5], [20]]
    *
    * See also:
    *

src/function/algebra/solver/lsolveAll.js

@@ -28,7 +28,7 @@ export const createLsolveAll = /* #__PURE__ */ factory(name, dependencies, ({ ty
    *
    *    const a = [[-2, 3], [2, 1]]
    *    const b = [11, 9]
-   *    const x = lsolveAll(a, b)  // [ [[-5.5], [20]] ]
+   *    math.lsolveAll(a, b)  // [ [[-5.5], [20]] ]
    *
    * See also:
    *

src/function/algebra/solver/usolve.js

@@ -28,7 +28,7 @@ export const createUsolve = /* #__PURE__ */ factory(name, dependencies, ({ typed
    *
    *    const a = [[-2, 3], [2, 1]]
    *    const b = [11, 9]
-   *    const x = usolve(a, b)  // [[8], [9]]
+   *    math.usolve(a, b)  // [[8], [9]]
    *
    * See also:
    *

src/function/algebra/solver/usolveAll.js

@@ -28,7 +28,7 @@ export const createUsolveAll = /* #__PURE__ */ factory(name, dependencies, ({ ty
    *
    *    const a = [[-2, 3], [2, 1]]
    *    const b = [11, 9]
-   *    const x = usolveAll(a, b)  // [ [[8], [9]] ]
+   *    math.usolveAll(a, b)  // [ [[8], [9]] ]
    *
    * See also:
    *

src/function/arithmetic/add.js

@@ -45,7 +45,7 @@ export const createAdd = /* #__PURE__ */ factory(
      *
      *    const c = math.unit('5 cm')
      *    const d = math.unit('2.1 mm')
-     *    math.add(c, d)               // returns Unit 52.1 mm
+     *    math.add(c, d)               // returns Unit 5.21 cm
      *
      *    math.add("2.3", "4")         // returns number 6.3
      *

src/function/arithmetic/cbrt.js

@@ -37,11 +37,8 @@ export const createCbrt = /* #__PURE__ */ factory(name, dependencies, ({ config,
    *
    *    const x = math.complex('8i')
    *    math.cbrt(x)                   // returns Complex 1.7320508075689 + i
-   *    math.cbrt(x, true)             // returns Matrix [
-   *                                    //    1.7320508075689 + i
-   *                                    //   -1.7320508075689 + i
-   *                                    //   -2i
-   *                                    // ]
+   *    math.cbrt(x, true)
+   *        // returns [1.7320508075689 + i, -1.7320508075689 + i, -2i]
    *
    * See also:
    *

src/function/arithmetic/dotDivide.js

@@ -37,9 +37,8 @@ export const createDotDivide = /* #__PURE__ */ factory(name, dependencies, ({ ty
    *
    *    math.dotDivide(2, 4)   // returns 0.5
    *
-   *    a = [[9, 5], [6, 1]]
-   *    b = [[3, 2], [5, 2]]
-   *
+   *    const a = [[9, 5], [6, 1]]
+   *    const b = [[3, 2], [5, 2]]
    *    math.dotDivide(a, b)   // returns [[3, 2.5], [1.2, 0.5]]
    *    math.divide(a, b)      // returns [[1.75, 0.75], [-1.75, 2.25]]
    *