Move constancy into Dynamic.

doc/src/SUMMARY.md

@@ -75,7 +75,7 @@ The Rhai Scripting Language
    5. [Variables](language/variables.md)
    6. [Constants](language/constants.md)
    7. [Logic Operators](language/logic.md)
-   8. [Other Operators](language/other-op.md)
+   8. [Assignment Operators](language/assignment-op.md)
    9. [If Statement](language/if.md)
    10. [Switch Expression](language/switch.md)
    11. [While Loop](language/while.md)

doc/src/engine/optimize/index.md

@@ -64,6 +64,15 @@ are spliced into the script text in order to turn on/off certain sections.
 For fixed script texts, the constant values can be provided in a user-defined [`Scope`] object
 to the [`Engine`] for use in compilation and evaluation.
 
+### Caveat
+
+If the [constants] are modified later on (yes, it is possible, via Rust functions),
+the modified values will not show up in the optimized script.
+Only the initialization values of [constants] are ever retained.
+
+This is almost never a problem because real-world scripts seldom modify a constant,
+but the possibility is always there.
+
 
 Eager Operator Evaluations
 -------------------------

doc/src/engine/optimize/optimize-levels.md

@@ -11,6 +11,14 @@ There are three levels of optimization: `None`, `Simple` and `Full`.
   (i.e. it only relies on static analysis and [built-in operators] for constant [standard types],
   and will not perform any external function calls).
 
+  However, it is important to bear in mind that _constants propagation_ is performed with the
+  caveat that, if [constants] are modified later on (yes, it is possible, via Rust functions),
+  the modified values will not show up in the optimized script.  Only the initialization values
+  of [constants] are ever retained.
+
+  Furthermore, overriding a [built-in operator][built-in operators] in the [`Engine`] afterwards
+  has no effect after the optimizer replaces an expression with its calculated value.
+
 * `Full` is _much_ more aggressive, _including_ calling external functions on constant arguments to determine their result.
   One benefit to this is that many more optimization opportunities arise, especially with regards to comparison operators.
 

doc/src/language/assignment-op.md

@@ -1,12 +1,9 @@
-Other Operators
-===============
+Compound Assignment Operators
+=============================
 
 {{#include ../links.md}}
 
 
-Compound Assignment Operators
-----------------------------
-
 ```rust
 let number = 9;
 
@@ -64,3 +61,6 @@ my_obj += #{c:3, d:4, e:5};
 
 my_obj.len() == 5;
 ```
+
+In fact, the `+` and `+=` operators are usually [overloaded][function overloading] when
+something is to be _added_ to an existing type.

doc/src/language/constants.md

@@ -61,9 +61,31 @@ r"
 ```
 
 
-Constants Can be Modified, Just Not Reassigned
----------------------------------------------
+Constants Can be Modified via Rust
+---------------------------------
 
-A custom type stored as a constant can be modified via its registered API -
-being a constant only prevents it from being re-assigned or operated upon by Rhai;
-mutating it via a Rust function is still allowed.
+A custom type stored as a constant cannot be modified via script, but _can_ be modified via
+a registered Rust function that takes a first `&mut` parameter - because there is no way for
+Rhai to know whether the Rust function modifies its argument!
+
+```rust
+const x = 42;       // a constant
+
+x.increment();      // call 'increment' defined in Rust with '&mut' first parameter
+
+x == 43;            // value of 'x' is changed!
+
+fn double() {
+    this *= 2;      // function squares 'this'
+}
+
+x.double();         // <- error: cannot modify constant 'this'
+
+x == 43;            // value of 'x' is unchanged by script
+```
+
+This is important to keep in mind because the script [optimizer][script optimization]
+by default does _constant propagation_ as a operation.
+
+If a constant is eventually modified by a Rust function, the optimizer will not see
+the updated value and will propagate the original initialization value instead.

doc/src/links.md

@@ -68,6 +68,8 @@
 
 [variable]: {{rootUrl}}/language/variables.md
 [variables]: {{rootUrl}}/language/variables.md
+[constant]: {{rootUrl}}/language/constants.md
+[constants]: {{rootUrl}}/language/constants.md
 
 [string]: {{rootUrl}}/language/strings-chars.md
 [strings]: {{rootUrl}}/language/strings-chars.md