Merge commit 'b52fb5234cd7c11ecfae51897a6f7fa52e8777fc' into clippyup

1 files changed, 39 insertions, 0 deletions

diff --git a/src/docs/wrong_self_convention.txt b/src/docs/wrong_self_convention.txt
new file mode 100644
index 00000000000..d6b69ab87f8
--- /dev/null
+++ b/src/docs/wrong_self_convention.txt
@@ -0,0 +1,39 @@
+### What it does
+Checks for methods with certain name prefixes and which
+doesn't match how self is taken. The actual rules are:
+
+|Prefix |Postfix     |`self` taken                   | `self` type  |
+|-------|------------|-------------------------------|--------------|
+|`as_`  | none       |`&self` or `&mut self`         | any          |
+|`from_`| none       | none                          | any          |
+|`into_`| none       |`self`                         | any          |
+|`is_`  | none       |`&mut self` or `&self` or none | any          |
+|`to_`  | `_mut`     |`&mut self`                    | any          |
+|`to_`  | not `_mut` |`self`                         | `Copy`       |
+|`to_`  | not `_mut` |`&self`                        | not `Copy`   |
+
+Note: Clippy doesn't trigger methods with `to_` prefix in:
+- Traits definition.
+Clippy can not tell if a type that implements a trait is `Copy` or not.
+- Traits implementation, when `&self` is taken.
+The method signature is controlled by the trait and often `&self` is required for all types that implement the trait
+(see e.g. the `std::string::ToString` trait).
+
+Clippy allows `Pin<&Self>` and `Pin<&mut Self>` if `&self` and `&mut self` is required.
+
+Please find more info here:
+https://rust-lang.github.io/api-guidelines/naming.html#ad-hoc-conversions-follow-as_-to_-into_-conventions-c-conv
+
+### Why is this bad?
+Consistency breeds readability. If you follow the
+conventions, your users won't be surprised that they, e.g., need to supply a
+mutable reference to a `as_..` function.
+
+### Example
+```
+impl X {
+    fn as_str(self) -> &'static str {
+        // ..
+    }
+}
+```
\ No newline at end of file