Rewrite documentation for yield-in-init (#2748)

crates/ruff/src/rules/pylint/rules/yield_in_init.rs

@@ -14,13 +14,15 @@ use crate::{
 define_violation!(
     /// ### What it does
     /// Checks for `__init__` methods that are turned into generators by the
-    /// inclusion of `yield` or `yield from` statements.
+    /// inclusion of `yield` or `yield from` expressions.
     ///
     /// ### Why is this bad?
-    /// The `__init__` method of a class is used to initialize new objects, not
+    /// The `__init__` method is the constructor for a given Python class,
-    /// create them. As such, it should not return any value. By including a
+    /// responsible for initializing, rather than creating, new objects.
-    /// yield expression in the method turns it into a generator method. On
+    ///
-    /// calling, it will return a generator resulting in a runtime error.
+    /// The `__init__` method has to return `None`. By including a `yield` or
+    /// `yield from` expression in an `__init__`, the method will return a
+    /// generator object when called at runtime, resulting in a runtime error.
     ///
     /// ### Example
     /// ```python

docs/rules/yield-in-init.md

@@ -4,13 +4,15 @@ Derived from the **Pylint** linter.
 
 ### What it does
 Checks for `__init__` methods that are turned into generators by the
-inclusion of `yield` or `yield from` statements.
+inclusion of `yield` or `yield from` expressions.
 
 ### Why is this bad?
-The `__init__` method of a class is used to initialize new objects, not
+The `__init__` method is the constructor for a given Python class,
-create them. As such, it should not return any value. By including a
+responsible for initializing, rather than creating, new objects.
-yield expression in the method turns it into a generator method. On
+
-calling, it will return a generator resulting in a runtime error.
+The `__init__` method has to return `None`. By including a `yield` or
+`yield from` expression in an `__init__`, the method will return a
+generator object when called at runtime, resulting in a runtime error.
 
 ### Example
 ```python