Update docs.

doc/src/rust/getters-setters.md

@@ -5,6 +5,8 @@ Custom Type Getters and Setters
 
 A custom type can also expose members by registering `get` and/or `set` functions.
 
+Getters and setters each take a `&mut` reference to the first parameter.
+
 ```rust
 #[derive(Clone)]
 struct TestStruct {

doc/src/rust/indexers.md

@@ -7,6 +7,8 @@ A custom type can also expose an _indexer_ by registering an indexer function.
 
 A custom type with an indexer function defined can use the bracket '`[]`' notation to get a property value.
 
+Like getters and setters, indexers take a `&mut` reference to the first parameter.
+
 Indexers are disabled when the [`no_index`] feature is used.
 
 For efficiency reasons, indexers **cannot** be used to overload (i.e. override) built-in indexing operations for
@@ -33,12 +35,10 @@ impl TestStruct {
 
 let mut engine = Engine::new();
 
-engine.register_type::<TestStruct>();
-
-engine.register_fn("new_ts", TestStruct::new);
-
-// Shorthand: engine.register_indexer_get_set(TestStruct::get_field, TestStruct::set_field);
 engine
+    .register_type::<TestStruct>()
+    .register_fn("new_ts", TestStruct::new)
+    // Shorthand: .register_indexer_get_set(TestStruct::get_field, TestStruct::set_field);
     .register_indexer_get(TestStruct::get_field)
     .register_indexer_set(TestStruct::set_field);
 

doc/src/rust/strings.md

@@ -3,11 +3,19 @@
 
 {{#include ../links.md}}
 
-Rust functions accepting parameters of `String` should use `&str` instead because it maps directly to [`ImmutableString`]
-which is the type that Rhai uses to represent [strings] internally.
+
+`&str` Maps to `ImmutableString`
+-------------------------------
+
+Rust functions accepting parameters of `String` should use `&str` instead because it maps directly to
+[`ImmutableString`][string] which is the type that Rhai uses to represent [strings] internally.
+
+The parameter type `String` is discouraged because it involves converting an [`ImmutableString`] into a `String`.
+Using `ImmutableString` or `&str` is much more efficient.
+A common mistake made by novice Rhai users is to register functions with `String` parameters.
 
 ```rust
-fn get_len1(s: String) -> i64 { s.len() as i64 }            // <- Rhai will not find this function
+fn get_len1(s: String) -> i64 { s.len() as i64 }            // <- Rhai finds this function, but very inefficient
 fn get_len2(s: &str) -> i64 { s.len() as i64 }              // <- Rhai finds this function fine
 fn get_len3(s: ImmutableString) -> i64 { s.len() as i64 }   // <- the above is equivalent to this
 
@@ -20,3 +28,23 @@ let len = engine.eval::<i64>("x.len1()")?;                  // error: function '
 let len = engine.eval::<i64>("x.len2()")?;                  // works fine
 let len = engine.eval::<i64>("x.len3()")?;                  // works fine
 ```
+
+
+Avoid `&mut ImmutableString`
+---------------------------
+
+Rhai functions can take a first `&mut` parameter.  Usually this is a good idea because it avoids
+cloning of the argument (except for primary types where cloning is cheap), so its use is encouraged
+even though there is no intention to ever mutate that argument.
+
+`ImmutableString` is an exception to this rule.  While `ImmutableString` is cheap to clone (only
+incrementing a reference count), taking a mutable reference to it involves making a private clone
+of the underlying string because Rhai has no way to find out whether that parameter will be mutated.
+
+If the `ImmutableString` is not shared by any other variables, then Rhai just returns a mutable
+reference to it since nobody else is watching! Otherwise a private copy is made first,
+because other reference holders will not expect the `ImmutableString` to ever change
+(it is supposed to be _immutable_).
+
+Therefore, avoid using `&mut ImmutableString` as the first parameter of a function unless you really
+intend to mutate that string.  Use `ImmutableString` instead.