1 files changed, 28 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/toplevel_ref_arg.txt b/src/tools/clippy/src/docs/toplevel_ref_arg.txt
new file mode 100644
index 000000000..96a9e2db8
--- /dev/null
+++ b/src/tools/clippy/src/docs/toplevel_ref_arg.txt
@@ -0,0 +1,28 @@
+### What it does
+Checks for function arguments and let bindings denoted as
+`ref`.
+
+### Why is this bad?
+The `ref` declaration makes the function take an owned
+value, but turns the argument into a reference (which means that the value
+is destroyed when exiting the function). This adds not much value: either
+take a reference type, or take an owned value and create references in the
+body.
+
+For let bindings, `let x = &foo;` is preferred over `let ref x = foo`. The
+type of `x` is more obvious with the former.
+
+### Known problems
+If the argument is dereferenced within the function,
+removing the `ref` will lead to errors. This can be fixed by removing the
+dereferences, e.g., changing `*x` to `x` within the function.
+
+### Example
+```
+fn foo(ref _x: u8) {}
+```
+
+Use instead:
+```
+fn foo(_x: &u8) {}
+```
+\ No newline at end of file