1 files changed, 27 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/string_add.txt b/src/tools/clippy/src/docs/string_add.txt
new file mode 100644
index 000000000..23dafd0d0
--- /dev/null
+++ b/src/tools/clippy/src/docs/string_add.txt
@@ -0,0 +1,27 @@
+### What it does
+Checks for all instances of `x + _` where `x` is of type
+`String`, but only if [`string_add_assign`](#string_add_assign) does *not*
+match.
+
+### Why is this bad?
+It's not bad in and of itself. However, this particular
+`Add` implementation is asymmetric (the other operand need not be `String`,
+but `x` does), while addition as mathematically defined is symmetric, also
+the `String::push_str(_)` function is a perfectly good replacement.
+Therefore, some dislike it and wish not to have it in their code.
+
+That said, other people think that string addition, having a long tradition
+in other languages is actually fine, which is why we decided to make this
+particular lint `allow` by default.
+
+### Example
+```
+let x = "Hello".to_owned();
+x + ", World";
+```
+
+Use instead:
+```
+let mut x = "Hello".to_owned();
+x.push_str(", World");
+```
+\ No newline at end of file