1 files changed, 43 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/trivially_copy_pass_by_ref.txt b/src/tools/clippy/src/docs/trivially_copy_pass_by_ref.txt
new file mode 100644
index 000000000..f54cce5e2
--- /dev/null
+++ b/src/tools/clippy/src/docs/trivially_copy_pass_by_ref.txt
@@ -0,0 +1,43 @@
+### What it does
+Checks for functions taking arguments by reference, where
+the argument type is `Copy` and small enough to be more efficient to always
+pass by value.
+
+### Why is this bad?
+In many calling conventions instances of structs will
+be passed through registers if they fit into two or less general purpose
+registers.
+
+### Known problems
+This lint is target register size dependent, it is
+limited to 32-bit to try and reduce portability problems between 32 and
+64-bit, but if you are compiling for 8 or 16-bit targets then the limit
+will be different.
+
+The configuration option `trivial_copy_size_limit` can be set to override
+this limit for a project.
+
+This lint attempts to allow passing arguments by reference if a reference
+to that argument is returned. This is implemented by comparing the lifetime
+of the argument and return value for equality. However, this can cause
+false positives in cases involving multiple lifetimes that are bounded by
+each other.
+
+Also, it does not take account of other similar cases where getting memory addresses
+matters; namely, returning the pointer to the argument in question,
+and passing the argument, as both references and pointers,
+to a function that needs the memory address. For further details, refer to
+[this issue](https://github.com/rust-lang/rust-clippy/issues/5953)
+that explains a real case in which this false positive
+led to an **undefined behavior** introduced with unsafe code.
+
+### Example
+
+```
+fn foo(v: &u32) {}
+```
+
+Use instead:
+```
+fn foo(v: u32) {}
+```
+\ No newline at end of file