Improve docs for PYI019 (#16229)

Author: AlexWaygood

crates/ruff_linter/src/rules/flake8_pyi/rules/custom_type_var_for_self.rs

@@ -31,6 +31,10 @@ use crate::settings::types::PythonVersion;
 /// ## Example
 ///
 /// ```pyi
+/// from typing import TypeVar
+///
+/// _S = TypeVar("_S", bound="Foo")
+///
 /// class Foo:
 ///     def __new__(cls: type[_S], *args: str, **kwargs: int) -> _S: ...
 ///     def foo(self: _S, arg: bytes) -> _S: ...
@@ -51,13 +55,21 @@ use crate::settings::types::PythonVersion;
 /// ```
 ///
 /// ## Fix behaviour and safety
-/// The fix removes all usages and declarations of the custom type variable.
-/// [PEP-695]-style `TypeVar` declarations are also removed from the [type parameter list];
-/// however, old-style `TypeVar`s do not have their declarations removed. See
-/// [`unused-private-type-var`][PYI018] for a rule to clean up unused private type variables.
+/// The fix replaces all references to the custom type variable in the method's header and body
+/// with references to `Self`. The fix also adds an import of `Self` if neither `Self` nor `typing`
+/// is already imported in the module. If your [`target-version`] setting is set to Python 3.11 or
+/// newer, the fix imports `Self` from the standard-library `typing` module; otherwise, the fix
+/// imports `Self` from the third-party [`typing_extensions`][typing_extensions] backport package.
+///
+/// If the custom type variable is a [PEP-695]-style `TypeVar`, the fix also removes the `TypeVar`
+/// declaration from the method's [type parameter list]. However, if the type variable is an
+/// old-style `TypeVar`, the declaration of the type variable will not be removed by this rule's
+/// fix, as the type variable could still be used by other functions, methods or classes. See
+/// [`unused-private-type-var`][PYI018] for a rule that will clean up unused private type
+/// variables.
 ///
-/// If there are any comments within the fix ranges, it will be marked as unsafe.
-/// Otherwise, it will be marked as safe.
+/// The fix is only marked as unsafe if there is the possibility that it might delete a comment
+/// from your code.
 ///
 /// ## Preview-mode behaviour
 /// This rule's behaviour has several differences when [`preview`] mode is enabled:
@@ -77,6 +89,7 @@ use crate::settings::types::PythonVersion;
 /// [type parameter list]: https://docs.python.org/3/reference/compound_stmts.html#type-params
 /// [Self]: https://docs.python.org/3/library/typing.html#typing.Self
 /// [typing_TypeVar]: https://docs.python.org/3/library/typing.html#typing.TypeVar
+/// [typing_extensions]: https://typing-extensions.readthedocs.io/en/latest/
 #[derive(ViolationMetadata)]
 pub(crate) struct CustomTypeVarForSelf {
     typevar_name: String,