1 files changed, 39 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/suspicious_to_owned.txt b/src/tools/clippy/src/docs/suspicious_to_owned.txt
new file mode 100644
index 000000000..8cbf61dc7
--- /dev/null
+++ b/src/tools/clippy/src/docs/suspicious_to_owned.txt
@@ -0,0 +1,39 @@
+### What it does
+Checks for the usage of `_.to_owned()`, on a `Cow<'_, _>`.
+
+### Why is this bad?
+Calling `to_owned()` on a `Cow` creates a clone of the `Cow`
+itself, without taking ownership of the `Cow` contents (i.e.
+it's equivalent to calling `Cow::clone`).
+The similarly named `into_owned` method, on the other hand,
+clones the `Cow` contents, effectively turning any `Cow::Borrowed`
+into a `Cow::Owned`.
+
+Given the potential ambiguity, consider replacing `to_owned`
+with `clone` for better readability or, if getting a `Cow::Owned`
+was the original intent, using `into_owned` instead.
+
+### Example
+```
+let s = "Hello world!";
+let cow = Cow::Borrowed(s);
+
+let data = cow.to_owned();
+assert!(matches!(data, Cow::Borrowed(_)))
+```
+Use instead:
+```
+let s = "Hello world!";
+let cow = Cow::Borrowed(s);
+
+let data = cow.clone();
+assert!(matches!(data, Cow::Borrowed(_)))
+```
+or
+```
+let s = "Hello world!";
+let cow = Cow::Borrowed(s);
+
+let data = cow.into_owned();
+assert!(matches!(data, String))
+```
+\ No newline at end of file