@@ -525,17 +525,20 @@ export interface BoxedExpression {
525525 */
526526readonly op3 :BoxedExpression ;
527527
528- /** If true, the value of the expression never changesand evaluating it has
529- * no side-effects.
528+ /** If* true* , the value of the expression never changes(provided the state of the engine does not
529+ *change), and evaluating it has no side-effects.
530530 *
531- * If false, the value of the expression may change, if the
532- * value of other expression changes or for other reasons.
533- *
534- * If `this.isPure` is `false`, `this.value` is undefined. Call
535- * `this.evaluate()` (or '*this.N()*') to determine the value of the expression instead.
531+ * If *false*, the value of the expression may differ for each request to it (see `evaluate()` or `N().valueOf()`).
536532 *
537533 * As an example, the `Random` function is not pure.
538534 *
535+ * A requirement for the definition of a pure function is that all of its arguments are pure too.
536+ * Said differently, if this is a function, it must be a pure function *expression*, too.
537+ *
538+ * This expression being pure (and a function) does not guarantee that the returned value will be
539+ * the same every time (i.e. that it is constant). To guarantee this, also check that `isConstant
540+ * === true`.
541+ *
539542 * :::info[Note]
540543 * Applicable to canonical and non-canonical expressions.
541544 * :::
@@ -553,7 +556,7 @@ export interface BoxedExpression {
553556 * - `2` is constant
554557 * - `Pi` is constant
555558 * - `["Add", "Pi", 2]` is constant
556- * - `x` is inconstant: unless declared with a constantvalue .
559+ * - `x` is inconstant: unless declared with a constantflag .
557560 * - `["Add", "x", 2]` is either constant or inconstant, depending on whether `x` is constant.
558561 */
559562readonly isConstant :boolean ;
@@ -1136,23 +1139,18 @@ export interface BoxedExpression {
11361139/**
11371140 * Return the value of the canonical form of this expression.
11381141 *
1139- * A pure expression always return the same value and has no side effects.
1142+ * A pure expression always returns the same value (provided that it remains constant / values of
1143+ * sub-expressions or symbols do not change), and has no side effects.
11401144 * If `expr.isPure` is `true`, `expr.value` and `expr.evaluate()` are
11411145 * synonyms.
11421146 *
1143- * For an impure expression, `expr.value` is undefined.
1144- *
1145- * Evaluating an impure expression may have some side effects, for
1146- * example modifying the `ComputeEngine` environment, such as its set of
1147- * assumptions.
1148- *
1149- * The result may be a rational number or the product of a rational number
1150- * and the square root of an integer.
1147+ * Evaluating an impure expression may return a varying value, and may have some side effects such
1148+ * adjusting symbol assumptions.
11511149 *
11521150 * To perform approximate calculations, use `expr.N()` instead,
1153- * orset `options.numericApproximation` to `true`.
1151+ * orcall with `options.numericApproximation` to `true`.
11541152 *
1155- *The result of `expr.evaluate()` may be the same as `expr.simplify()`.
1153+ *It is possible that the result of `expr.evaluate()` may be the same as `expr.simplify()`.
11561154 *
11571155 * The result is in canonical form.
11581156 *
@@ -1233,6 +1231,12 @@ export interface BoxedExpression {
12331231 *
12341232 * Otherwise, return `undefined`.
12351233 *
1234+ * :::info[Note]
1235+ * The expression's value may depend on the current state of the engine. For instance, if a
1236+ * non-constant symbol, the value is subject to change via value assignments and assumptions about
1237+ * its value. Also, for both numbers and symbols: the *representation* of the value may depend on
1238+ * the current engine precision.
1239+ *
12361240 */
12371241get value ( ) :number | boolean | string | undefined ;
12381242