doc: skip-calls etc

NEWS.md

@@ -1,5 +1,11 @@
 # cargo-mutants changelog
 
+## Unreleased
+
+- Changed: The arguments of calls to functions or methods named `with_capacity` are not mutated by default. This can be turned off with `--skip-calls-defaults=false` on the command line or `skip_calls_defaults = false` in `.cargo/mutants.toml`.
+
+- New: `--skip-calls=NAME,NAME` on the command line or `skip_calls = [NAMES..]` in `.cargo/mutants.toml` allows configuring other functions whose calls should never be mutated.
+
 ## 24.11.0
 
 - New: `--test-workspace` and `--test-package` arguments and config options support projects whose tests live in a different package.

book/src/SUMMARY.md

@@ -9,6 +9,7 @@
   - [The `mutants.out` directory](mutants-out.md)
 - [Skipping untestable code](skip.md)
   - [Skipping functions with an attribute](attrs.md)
+  - [Skipping function calls](skip_calls.md)
   - [Filtering files](skip_files.md)
   - [Filtering functions and mutants](filter_mutants.md)
 - [Controlling cargo-mutants](controlling.md)

book/src/skip_calls.md

@@ -0,0 +1,37 @@
+# Skipping function calls
+
+Using the `--skip-calls` argument and config key you can tell cargo-mutants not to mutate the arguments to calls to specific named functions and methods.
+
+For example:
+
+```sh
+cargo mutants --skip-calls=skip_this,and_this
+```
+
+or in `.cargo/mutants.toml`
+
+```toml
+skip_calls = ["skip_this", "and_this"]
+```
+
+The command line arguments are added to the values specified in the configuration.
+
+The names given in the option and argument are matched against the final component of the path in each call, disregarding any type parameters. For example, the default value of `with_capacity` will match `std::vec::Vec::<String>::with_capacity(10)`.
+
+This is separate from [skipping mutation of the body of a function](attrs.md), and only affects the generation of mutants within the call expression, typically in its arguments.
+
+By default, calls to functions called `with_capacity` are not mutated. The defaults can be turned off using `--skip-calls-defaults=false`.
+
+## `with_capacity`
+
+The motivating example for this feature is Rust's `with_capacity` function on `Vec` and other collections, which preallocates capacity for a slight performance gain.
+
+```rust
+    let mut v = Vec::with_capacity(4 * n);
+```
+
+cargo-mutants normally mutates expressions in function calls, and in this case it will try mutating the capacity expression to `4 / n` etc.
+
+These mutations would change the program behavior. Assuming the original calculation is correct the mutation then the mutation will likly be wrong.
+
+However, many authors may feel that preallocating the estimated memory needs is worth doing but not worth specifically writing tests or assertions for, and so they would like to skip generating mutants in any calls to these functions.

src/visit.rs

@@ -1003,7 +1003,7 @@ mod test {
         let mutants = mutate_source_str(
             indoc! {"
                 fn main() {
-                    let mut v = Vec::with_capacity(2 * 100);
+                    let mut _v = std::vec::Vec::<String>::with_capacity(2 * 100);
                 }
             "},
             &options,