Add `flake8-pie` documentation (#4332)

crates/ruff/src/rules/flake8_pie/rules.rs

@@ -20,6 +20,30 @@ use crate::autofix::actions::delete_stmt;
 use crate::checkers::ast::Checker;
 use crate::registry::AsRule;
 
+/// ## What it does
+/// Checks for unnecessary `pass` statements in class and function bodies.
+/// where it is not needed syntactically (e.g., when an indented docstring is
+/// present).
+///
+/// ## Why is this bad?
+/// When a function or class definition contains a docstring, an additional
+/// `pass` statement is redundant.
+///
+/// ## Example
+/// ```python
+/// def foo():
+///     """Placeholder docstring."""
+///     pass
+/// ```
+///
+/// Use instead:
+/// ```python
+/// def foo():
+///     """Placeholder docstring."""
+/// ```
+///
+/// ## References
+/// - [Python documentation](https://docs.python.org/3/reference/simple_stmts.html#the-pass-statement)
 #[violation]
 pub struct UnnecessaryPass;
 
@@ -34,6 +58,27 @@ impl AlwaysAutofixableViolation for UnnecessaryPass {
     }
 }
 
+/// ## What it does
+/// Checks for duplicate field definitions in classes.
+///
+/// ## Why is this bad?
+/// Defining a field multiple times in a class body is redundant and likely a
+/// mistake.
+///
+/// ## Example
+/// ```python
+/// class Person:
+///     name = Tom
+///     ...
+///     name = Ben
+/// ```
+///
+/// Use instead:
+/// ```python
+/// class Person:
+///     name = Tom
+///     ...
+/// ```
 #[violation]
 pub struct DuplicateClassFieldDefinition(pub String);
 
@@ -50,6 +95,37 @@ impl AlwaysAutofixableViolation for DuplicateClassFieldDefinition {
     }
 }
 
+/// ## What it does
+/// Checks for enums that contain duplicate values.
+///
+/// ## Why is this bad?
+/// Enum values should be unique. Non-unique values are redundant and likely a
+/// mistake.
+///
+/// ## Example
+/// ```python
+/// from enum import Enum
+///
+///
+/// class Foo(Enum):
+///     A = 1
+///     B = 2
+///     C = 1
+/// ```
+///
+/// Use instead:
+/// ```python
+/// from enum import Enum
+///
+///
+/// class Foo(Enum):
+///     A = 1
+///     B = 2
+///     C = 3
+/// ```
+///
+/// ## References
+/// - [Python documentation](https://docs.python.org/3/library/enum.html#enum.Enum)
 #[violation]
 pub struct NonUniqueEnums {
     value: String,
@@ -63,6 +139,27 @@ impl Violation for NonUniqueEnums {
     }
 }
 
+/// ## What it does
+/// Checks for unnecessary dictionary unpacking operators (`**`).
+///
+/// ## Why is this bad?
+/// Unpacking a dictionary into another dictionary is redundant. The unpacking
+/// operator can be removed, making the code more readable.
+///
+/// ## Example
+/// ```python
+/// foo = {"A": 1, "B": 2}
+/// bar = {**foo, **{"C": 3}}
+/// ```
+///
+/// Use instead:
+/// ```python
+/// foo = {"A": 1, "B": 2}
+/// bar = {**foo, "C": 3}
+/// ```
+///
+/// ## References
+/// - [Python documentation](https://docs.python.org/3/reference/expressions.html#dictionary-displays)
 #[violation]
 pub struct UnnecessarySpread;
 
@@ -73,6 +170,32 @@ impl Violation for UnnecessarySpread {
     }
 }
 
+/// ## What it does
+/// Checks for `startswith` or `endswith` calls on the same value with
+/// different prefixes or suffixes.
+///
+/// ## Why is this bad?
+/// The `startswith` and `endswith` methods accept tuples of prefixes or
+/// suffixes respectively. Passing a tuple of prefixes or suffixes is more
+/// more efficient and readable than calling the method multiple times.
+///
+/// ## Example
+/// ```python
+/// msg = "Hello, world!"
+/// if msg.startswith("Hello") or msg.startswith("Hi"):
+///     print("Greetings!")
+/// ```
+///
+/// Use instead:
+/// ```python
+/// msg = "Hello, world!"
+/// if msg.startswith(("Hello", "Hi")):
+///     print("Greetings!")
+/// ```
+///
+/// ## References
+/// - [Python documentation](https://docs.python.org/3/library/stdtypes.html#str.startswith)
+/// - [Python documentation](https://docs.python.org/3/library/stdtypes.html#str.endswith)
 #[violation]
 pub struct MultipleStartsEndsWith {
     attr: String,
@@ -91,6 +214,34 @@ impl AlwaysAutofixableViolation for MultipleStartsEndsWith {
     }
 }
 
+/// ## What it does
+/// Checks for unnecessary `dict` kwargs.
+///
+/// ## Why is this bad?
+/// If the `dict` keys are valid identifiers, they can be passed as keyword
+/// arguments directly.
+///
+/// ## Example
+/// ```python
+/// def foo(bar):
+///     return bar + 1
+///
+///
+/// print(foo(**{"bar": 2}))  # prints 3
+/// ```
+///
+/// Use instead:
+/// ```python
+/// def foo(bar):
+///     return bar + 1
+///
+///
+/// print(foo(bar=2))  # prints 3
+/// ```
+///
+/// ## References
+/// - [Python documentation](https://docs.python.org/3/reference/expressions.html#dictionary-displays)
+/// - [Python documentation](https://docs.python.org/3/reference/expressions.html#calls)
 #[violation]
 pub struct UnnecessaryDictKwargs;
 
@@ -101,6 +252,34 @@ impl Violation for UnnecessaryDictKwargs {
     }
 }
 
+/// ## What it does
+/// Checks for lambdas that can be replaced with the `list` builtin.
+///
+/// ## Why is this bad?
+/// Using `list` builtin is more readable.
+///
+/// ## Example
+/// ```python
+/// from dataclasses import dataclass, field
+///
+///
+/// @dataclass
+/// class Foo:
+///     bar: list[int] = field(default_factory=lambda: [])
+/// ```
+///
+/// Use instead:
+/// ```python
+/// from dataclasses import dataclass, field
+///
+///
+/// @dataclass
+/// class Foo:
+///     bar: list[int] = field(default_factory=list)
+/// ```
+///
+/// ## References
+/// - [Python documentation](https://docs.python.org/3/library/functions.html#func-list)
 #[violation]
 pub struct ReimplementedListBuiltin;