Add PD002 use-of-inplace-argument documentation (#2799)

README.md

@@ -1353,7 +1353,7 @@ For more, see [pandas-vet](https://pypi.org/project/pandas-vet/) on PyPI.
 
 | Code | Name | Message | Fix |
 | ---- | ---- | ------- | --- |
-| PD002 | use-of-inplace-argument | `inplace=True` should be avoided; it has inconsistent behavior | 🛠 |
+| PD002 | [use-of-inplace-argument](https://github.com/charliermarsh/ruff/blob/main/docs/rules/use-of-inplace-argument.md) | `inplace=True` should be avoided; it has inconsistent behavior | 🛠 |
 | PD003 | use-of-dot-is-null | `.isna` is preferred to `.isnull`; functionality is equivalent |  |
 | PD004 | use-of-dot-not-null | `.notna` is preferred to `.notnull`; functionality is equivalent |  |
 | PD007 | use-of-dot-ix | `.ix` is deprecated; use more explicit `.loc` or `.iloc` |  |

crates/ruff/src/rules/pandas_vet/rules/inplace_argument.rs

@@ -8,6 +8,30 @@ use crate::rules::pandas_vet::fixes::fix_inplace_argument;
 use crate::violation::AlwaysAutofixableViolation;
 
 define_violation!(
+    /// ## What it does
+    /// Checks for `inplace=True` usages in `pandas` function and method
+    /// calls.
+    ///
+    /// ## Why is this bad?
+    /// Using `inplace=True` encourages mutation rather than immutable data,
+    /// which is harder to reason about and may cause bugs. It also removes the
+    /// ability to use the method chaining style for `pandas` operations.
+    ///
+    /// Further, in many cases, `inplace=True` does not provide a performance
+    /// benefit, as `pandas` will often copy `DataFrames` in the background.
+    ///
+    /// ## Example
+    /// ```python
+    /// df.sort_values("col1", inplace=True)
+    /// ```
+    ///
+    /// Use instead:
+    /// ```python
+    /// sorted_df = df.sort_values("col1")
+    /// ```
+    ///
+    /// ## References
+    /// - [Why You Should Probably Never Use pandas inplace=True](https://towardsdatascience.com/why-you-should-probably-never-use-pandas-inplace-true-9f9f211849e4)
     pub struct UseOfInplaceArgument;
 );
 impl AlwaysAutofixableViolation for UseOfInplaceArgument {
@@ -17,7 +41,7 @@ impl AlwaysAutofixableViolation for UseOfInplaceArgument {
     }
 
     fn autofix_title(&self) -> String {
-        format!("Assign to variable and remove the `inplace` arg")
+        format!("Assign to variable; remove `inplace` arg")
     }
 }
 

docs/rules/use-of-inplace-argument.md

@@ -0,0 +1,30 @@
+# use-of-inplace-argument (PD002)
+
+Derived from the **pandas-vet** linter.
+
+Autofix is always available.
+
+## What it does
+Checks for `inplace=True` usages in `pandas` function and method
+calls.
+
+## Why is this bad?
+Using `inplace=True` encourages mutation rather than immutable data,
+which is harder to reason about and may cause bugs. It also removes the
+ability to use the method chaining style for `pandas` operations.
+
+Further, in many cases, `inplace=True` does not provide a performance
+benefit, as `pandas` will often copy `DataFrames` in the background.
+
+## Example
+```python
+df.sort_values("col1", inplace=True)
+```
+
+Use instead:
+```python
+sorted_df = df.sort_values("col1")
+```
+
+## References
+- [Why You Should Probably Never Use pandas inplace=True](https://towardsdatascience.com/why-you-should-probably-never-use-pandas-inplace-true-9f9f211849e4)