Update docs.

doc/src/language/method.md

@@ -3,6 +3,10 @@ Call Method as Function
 
 {{#include ../links.md}}
 
+
+First `&mut` Reference Parameter
+-------------------------------
+
 Property [getters/setters] and [methods][custom types] in a Rust custom type registered with the [`Engine`] can be called
 just like a regular function.  In fact, like Rust, property getters/setters and object methods
 are registered as regular [functions] in Rhai that take a first `&mut` parameter.
@@ -31,3 +35,23 @@ update(array[0]);   // <- 'array[0]' is an expression returning a calculated val
 
 array[0].update();  // <- call in method-call style will update 'a'
 ```
+
+
+Encouraged Usage
+----------------
+
+Using a `&mut` first parameter is highly encouraged when using types that are expensive to clone,
+even when the intention is not to mutate that argument, because it avoids cloning that argument value.
+
+For primary types that are cheap to clone, including `ImmutableString`, this is not necessary.
+
+
+Avoid `&mut ImmutableString`
+---------------------------
+
+`ImmutableString`, Rhai internal [string] type, is an exception.
+
+`ImmutableString` is cheap to clone, but expensive to take a mutable reference (because the underlying
+string must be cloned to make a private copy).
+
+Therefore, avoid using `&mut ImmutableString` unless the intention is to mutate it.