Docs: tweak rules documentation (#14180)

Co-authored-by: Micha Reiser <micha@reiser.io>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

crates/ruff_linter/src/rules/flake8_annotations/rules/definition.rs

@@ -469,7 +469,7 @@ impl Violation for MissingReturnTypeClassMethod {
 /// ```
 ///
 /// ## References
-/// - [PEP 484](https://www.python.org/dev/peps/pep-0484/#the-any-type)
+/// - [Typing spec: `Any`](https://typing.readthedocs.io/en/latest/spec/special-types.html#any)
 /// - [Python documentation: `typing.Any`](https://docs.python.org/3/library/typing.html#typing.Any)
 /// - [Mypy documentation: The Any type](https://mypy.readthedocs.io/en/stable/kinds_of_types.html#the-any-type)
 #[violation]

crates/ruff_linter/src/rules/flake8_bandit/rules/suspicious_imports.rs

@@ -10,16 +10,21 @@ use crate::checkers::ast::Checker;
 use crate::registry::AsRule;
 
 /// ## What it does
-/// Checks for imports of the`telnetlib` module.
+/// Checks for imports of the `telnetlib` module.
 ///
 /// ## Why is this bad?
-/// Telnet is considered insecure. Instead, use SSH or another encrypted
+/// Telnet is considered insecure. It is deprecated since version 3.11, and
+/// was removed in version 3.13. Instead, use SSH or another encrypted
 /// protocol.
 ///
 /// ## Example
 /// ```python
 /// import telnetlib
 /// ```
+///
+/// ## References
+/// - [Python documentation: `telnetlib` - Telnet client](https://docs.python.org/3.12/library/telnetlib.html#module-telnetlib)
+/// - [PEP 594: `telnetlib`](https://peps.python.org/pep-0594/#telnetlib)
 #[violation]
 pub struct SuspiciousTelnetlibImport;
 
@@ -41,6 +46,9 @@ impl Violation for SuspiciousTelnetlibImport {
 /// ```python
 /// import ftplib
 /// ```
+///
+/// ## References
+/// - [Python documentation: `ftplib` - FTP protocol client](https://docs.python.org/3/library/ftplib.html)
 #[violation]
 pub struct SuspiciousFtplibImport;
 
@@ -63,8 +71,9 @@ impl Violation for SuspiciousFtplibImport {
 /// ```python
 /// import pickle
 /// ```
+///
 /// ## References
-/// - [Python Docs](https://docs.python.org/3/library/pickle.html)
+/// - [Python documentation: `pickle` — Python object serialization](https://docs.python.org/3/library/pickle.html)
 #[violation]
 pub struct SuspiciousPickleImport;
 

crates/ruff_linter/src/rules/flake8_bandit/rules/tarfile_unsafe_members.rs

@@ -33,8 +33,8 @@ use ruff_text_size::Ranged;
 ///
 /// ## References
 /// - [Common Weakness Enumeration: CWE-22](https://cwe.mitre.org/data/definitions/22.html)
-/// - [Python Documentation: `TarFile.extractall`](https://docs.python.org/3/library/tarfile.html#tarfile.TarFile.extractall)
-/// - [Python Documentation: Extraction filters](https://docs.python.org/3/library/tarfile.html#tarfile-extraction-filter)
+/// - [Python documentation: `TarFile.extractall`](https://docs.python.org/3/library/tarfile.html#tarfile.TarFile.extractall)
+/// - [Python documentation: Extraction filters](https://docs.python.org/3/library/tarfile.html#tarfile-extraction-filter)
 ///
 /// [PEP 706]: https://peps.python.org/pep-0706/#backporting-forward-compatibility
 #[violation]

crates/ruff_linter/src/rules/flake8_blind_except/rules/blind_except.rs

@@ -60,7 +60,7 @@ use crate::checkers::ast::Checker;
 /// ## References
 /// - [Python documentation: The `try` statement](https://docs.python.org/3/reference/compound_stmts.html#the-try-statement)
 /// - [Python documentation: Exception hierarchy](https://docs.python.org/3/library/exceptions.html#exception-hierarchy)
-/// - [PEP8 Programming Recommendations on bare `except`](https://peps.python.org/pep-0008/#programming-recommendations)
+/// - [PEP 8: Programming Recommendations on bare `except`](https://peps.python.org/pep-0008/#programming-recommendations)
 #[violation]
 pub struct BlindExcept {
     name: String,

crates/ruff_linter/src/rules/flake8_bugbear/rules/abstract_base_class.rs

@@ -88,7 +88,7 @@ impl Violation for AbstractBaseClassWithoutAbstractMethod {
 /// ```
 ///
 /// ## References
-/// - [Python documentation: abc](https://docs.python.org/3/library/abc.html)
+/// - [Python documentation: `abc`](https://docs.python.org/3/library/abc.html)
 #[violation]
 pub struct EmptyMethodWithoutAbstractDecorator {
     name: String,

crates/ruff_linter/src/rules/flake8_bugbear/rules/f_string_docstring.rs

@@ -28,7 +28,7 @@ use crate::checkers::ast::Checker;
 /// ```
 ///
 /// ## References
-/// - [PEP 257](https://peps.python.org/pep-0257/)
+/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
 /// - [Python documentation: Formatted string literals](https://docs.python.org/3/reference/lexical_analysis.html#f-strings)
 #[violation]
 pub struct FStringDocstring;

crates/ruff_linter/src/rules/flake8_bugbear/rules/function_uses_loop_variable.rs

@@ -40,7 +40,7 @@ use crate::checkers::ast::Checker;
 ///
 /// ## References
 /// - [The Hitchhiker's Guide to Python: Late Binding Closures](https://docs.python-guide.org/writing/gotchas/#late-binding-closures)
-/// - [Python documentation: functools.partial](https://docs.python.org/3/library/functools.html#functools.partial)
+/// - [Python documentation: `functools.partial`](https://docs.python.org/3/library/functools.html#functools.partial)
 #[violation]
 pub struct FunctionUsesLoopVariable {
     name: String,

crates/ruff_linter/src/rules/flake8_bugbear/rules/no_explicit_stacklevel.rs

@@ -26,6 +26,9 @@ use crate::checkers::ast::Checker;
 /// ```python
 /// warnings.warn("This is a warning", stacklevel=2)
 /// ```
+///
+/// ## References
+/// - [Python documentation: `warnings.warn`](https://docs.python.org/3/library/warnings.html#warnings.warn)
 #[violation]
 pub struct NoExplicitStacklevel;
 

crates/ruff_linter/src/rules/flake8_bugbear/rules/useless_contextlib_suppress.rs

@@ -35,7 +35,7 @@ use crate::checkers::ast::Checker;
 /// ```
 ///
 /// ## References
-/// - [Python documentation: contextlib.suppress](https://docs.python.org/3/library/contextlib.html#contextlib.suppress)
+/// - [Python documentation: `contextlib.suppress`](https://docs.python.org/3/library/contextlib.html#contextlib.suppress)
 #[violation]
 pub struct UselessContextlibSuppress;
 

crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_dict_comprehension_for_iterable.rs

@@ -30,6 +30,9 @@ use crate::checkers::ast::Checker;
 /// dict.fromkeys(iterable)
 /// dict.fromkeys(iterable, 1)
 /// ```
+///
+/// ## References
+/// - [Python documentation: `dict.fromkeys`](https://docs.python.org/3/library/stdtypes.html#dict.fromkeys)
 #[violation]
 pub struct UnnecessaryDictComprehensionForIterable {
     is_value_none_literal: bool,
@@ -53,7 +56,7 @@ impl Violation for UnnecessaryDictComprehensionForIterable {
     }
 }
 
-/// RUF025
+/// C420
 pub(crate) fn unnecessary_dict_comprehension_for_iterable(
     checker: &mut Checker,
     dict_comp: &ast::ExprDictComp,

crates/ruff_linter/src/rules/flake8_gettext/rules/f_string_in_gettext_func_call.rs

@@ -39,7 +39,7 @@ use crate::checkers::ast::Checker;
 /// ```
 ///
 /// ## References
-/// - [Python documentation: gettext](https://docs.python.org/3/library/gettext.html)
+/// - [Python documentation: `gettext` — Multilingual internationalization services](https://docs.python.org/3/library/gettext.html)
 #[violation]
 pub struct FStringInGetTextFuncCall;
 

crates/ruff_linter/src/rules/flake8_gettext/rules/format_in_gettext_func_call.rs

@@ -39,7 +39,7 @@ use crate::checkers::ast::Checker;
 /// ```
 ///
 /// ## References
-/// - [Python documentation: gettext](https://docs.python.org/3/library/gettext.html)
+/// - [Python documentation: `gettext` — Multilingual internationalization services](https://docs.python.org/3/library/gettext.html)
 #[violation]
 pub struct FormatInGetTextFuncCall;
 

crates/ruff_linter/src/rules/flake8_gettext/rules/printf_in_gettext_func_call.rs

@@ -38,7 +38,7 @@ use ruff_text_size::Ranged;
 /// ```
 ///
 /// ## References
-/// - [Python documentation: gettext](https://docs.python.org/3/library/gettext.html)
+/// - [Python documentation: `gettext` — Multilingual internationalization services](https://docs.python.org/3/library/gettext.html)
 #[violation]
 pub struct PrintfInGetTextFuncCall;
 

crates/ruff_linter/src/rules/flake8_no_pep420/rules/implicit_namespace_package.rs

@@ -22,7 +22,7 @@ use crate::Locator;
 ///
 /// Directories that lack an `__init__.py` file can still be imported, but
 /// they're indicative of a special kind of package, known as a "namespace
-/// package" (see: [PEP 420](https://www.python.org/dev/peps/pep-0420/)).
+/// package" (see: [PEP 420](https://peps.python.org/pep-0420/)).
 /// Namespace packages are less widely used, so a package that lacks an
 /// `__init__.py` file is typically meant to be a regular package, and
 /// the absence of the `__init__.py` file is probably an oversight.

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

@@ -30,7 +30,7 @@ use crate::checkers::ast::Checker;
 /// ```
 ///
 /// ## References
-/// The [typing documentation on stub files](https://typing.readthedocs.io/en/latest/source/stubs.html#version-and-platform-checks)
+/// - [Typing documentation: Version and platform checking](https://typing.readthedocs.io/en/latest/spec/directives.html#version-and-platform-checks)
 #[violation]
 pub struct ComplexIfStatementInStub;
 

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

@@ -26,8 +26,7 @@ use crate::checkers::ast::Checker;
 /// ```
 ///
 /// ## References
-/// - [The recommended style for stub functions and methods](https://typing.readthedocs.io/en/latest/source/stubs.html#id6)
-///   in the typing docs.
+/// - [Typing documentation - Writing and Maintaining Stub Files](https://typing.readthedocs.io/en/latest/guides/writing_stubs.html)
 #[violation]
 pub struct NonEmptyStubBody;
 

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

@@ -71,7 +71,7 @@ use crate::checkers::ast::Checker;
 ///     def __iadd__(self, other: Foo) -> Self: ...
 /// ```
 /// ## References
-/// - [`typing.Self` documentation](https://docs.python.org/3/library/typing.html#typing.Self)
+/// - [Python documentation: `typing.Self`](https://docs.python.org/3/library/typing.html#typing.Self)
 #[violation]
 pub struct NonSelfReturnType {
     class_name: String,

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

@@ -23,8 +23,7 @@ use crate::checkers::ast::Checker;
 /// ```
 ///
 /// ## References
-/// The [recommended style for functions and methods](https://typing.readthedocs.io/en/latest/source/stubs.html#functions-and-methods)
-/// in the typing docs.
+/// - [Typing documentation - Writing and Maintaining Stub Files](https://typing.readthedocs.io/en/latest/guides/writing_stubs.html)
 #[violation]
 pub struct PassStatementStubBody;
 

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

@@ -27,7 +27,7 @@ use crate::checkers::ast::Checker;
 /// ```
 ///
 /// ## References
-/// - [Static Typing with Python: Type Stubs](https://typing.readthedocs.io/en/latest/source/stubs.html)
+/// - [Typing documentation - Writing and Maintaining Stub Files](https://typing.readthedocs.io/en/latest/guides/writing_stubs.html)
 #[violation]
 pub struct QuotedAnnotationInStub;
 

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

@@ -38,7 +38,7 @@ use crate::checkers::ast::Checker;
 /// ```
 ///
 /// ## References
-/// - [The typing specification](https://docs.python.org/3/library/numbers.html#the-numeric-tower)
+/// - [Python documentation: The numeric tower](https://docs.python.org/3/library/numbers.html#the-numeric-tower)
 /// - [PEP 484: The numeric tower](https://peps.python.org/pep-0484/#the-numeric-tower)
 ///
 /// [typing specification]: https://typing.readthedocs.io/en/latest/spec/special-types.html#special-cases-for-float-and-complex

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

@@ -40,7 +40,7 @@ use crate::registry::Rule;
 /// ```
 ///
 /// ## References
-/// - [Typing stubs documentation: Version and Platform Checks](https://typing.readthedocs.io/en/latest/source/stubs.html#version-and-platform-checks)
+/// - [Typing documentation: Version and Platform checking](https://typing.readthedocs.io/en/latest/spec/directives.html#version-and-platform-checks)
 #[violation]
 pub struct UnrecognizedPlatformCheck;
 
@@ -74,7 +74,7 @@ impl Violation for UnrecognizedPlatformCheck {
 /// ```
 ///
 /// ## References
-/// - [Typing stubs documentation: Version and Platform Checks](https://typing.readthedocs.io/en/latest/source/stubs.html#version-and-platform-checks)
+/// - [Typing documentation: Version and Platform checking](https://typing.readthedocs.io/en/latest/spec/directives.html#version-and-platform-checks)
 #[violation]
 pub struct UnrecognizedPlatformName {
     platform: String,

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

@@ -31,7 +31,7 @@ use crate::registry::Rule;
 /// ```
 ///
 /// ## References
-/// - [Typing stubs documentation: Version and Platform Checks](https://typing.readthedocs.io/en/latest/source/stubs.html#version-and-platform-checks)
+/// - [Typing documentation: Version and Platform checking](https://typing.readthedocs.io/en/latest/spec/directives.html#version-and-platform-checks)
 #[violation]
 pub struct UnrecognizedVersionInfoCheck;
 
@@ -70,7 +70,7 @@ impl Violation for UnrecognizedVersionInfoCheck {
 /// ```
 ///
 /// ## References
-/// - [Typing stubs documentation: Version and Platform Checks](https://typing.readthedocs.io/en/latest/source/stubs.html#version-and-platform-checks)
+/// - [Typing documentation: Version and Platform checking](https://typing.readthedocs.io/en/latest/spec/directives.html#version-and-platform-checks)
 #[violation]
 pub struct PatchVersionComparison;
 
@@ -106,7 +106,7 @@ impl Violation for PatchVersionComparison {
 /// ```
 ///
 /// ## References
-/// - [Typing stubs documentation: Version and Platform Checks](https://typing.readthedocs.io/en/latest/source/stubs.html#version-and-platform-checks)
+/// - [Typing documentation: Version and Platform checking](https://typing.readthedocs.io/en/latest/spec/directives.html#version-and-platform-checks)
 #[violation]
 pub struct WrongTupleLengthVersionComparison {
     expected_length: usize,

crates/ruff_linter/src/rules/flake8_pytest_style/rules/fixture.rs

@@ -590,7 +590,7 @@ impl AlwaysFixableViolation for PytestErroneousUseFixturesOnFixture {
 /// ```
 ///
 /// ## References
-/// - [`pytest-asyncio`](https://pypi.org/project/pytest-asyncio/)
+/// - [PyPI: `pytest-asyncio`](https://pypi.org/project/pytest-asyncio/)
 #[violation]
 pub struct PytestUnnecessaryAsyncioMarkOnFixture;
 

crates/ruff_linter/src/rules/flake8_pytest_style/rules/patch.rs

@@ -38,7 +38,7 @@ use ruff_text_size::Ranged;
 ///
 /// ## References
 /// - [Python documentation: `unittest.mock.patch`](https://docs.python.org/3/library/unittest.mock.html#unittest.mock.patch)
-/// - [`pytest-mock`](https://pypi.org/project/pytest-mock/)
+/// - [PyPI: `pytest-mock`](https://pypi.org/project/pytest-mock/)
 #[violation]
 pub struct PytestPatchWithLambda;
 

crates/ruff_linter/src/rules/flake8_type_checking/rules/empty_type_checking_block.rs

@@ -31,7 +31,7 @@ use crate::fix;
 /// ```
 ///
 /// ## References
-/// - [PEP 535](https://peps.python.org/pep-0563/#runtime-annotation-resolution-and-type-checking)
+/// - [PEP 563: Runtime annotation resolution and `TYPE_CHECKING`](https://peps.python.org/pep-0563/#runtime-annotation-resolution-and-type-checking)
 #[violation]
 pub struct EmptyTypeCheckingBlock;
 

crates/ruff_linter/src/rules/flake8_type_checking/rules/runtime_import_in_type_checking_block.rs

@@ -51,7 +51,7 @@ use crate::rules::flake8_type_checking::imports::ImportBinding;
 /// - `lint.flake8-type-checking.quote-annotations`
 ///
 /// ## References
-/// - [PEP 535](https://peps.python.org/pep-0563/#runtime-annotation-resolution-and-type-checking)
+/// - [PEP 563: Runtime annotation resolution and `TYPE_CHECKING`](https://peps.python.org/pep-0563/#runtime-annotation-resolution-and-type-checking)
 #[violation]
 pub struct RuntimeImportInTypeCheckingBlock {
     qualified_name: String,

crates/ruff_linter/src/rules/flake8_type_checking/rules/runtime_string_union.rs

@@ -37,8 +37,8 @@ use crate::checkers::ast::Checker;
 /// ```
 ///
 /// ## References
-/// - [PEP 535](https://peps.python.org/pep-0563/)
-/// - [PEP 604](https://peps.python.org/pep-0604/)
+/// - [PEP 563 - Postponed Evaluation of Annotations](https://peps.python.org/pep-0563/)
+/// - [PEP 604 – Allow writing union types as `X | Y`](https://peps.python.org/pep-0604/)
 ///
 /// [PEP 604]: https://peps.python.org/pep-0604/
 #[violation]

crates/ruff_linter/src/rules/flake8_type_checking/rules/typing_only_runtime_import.rs

@@ -71,7 +71,7 @@ use crate::rules::isort::{categorize, ImportSection, ImportType};
 /// - `lint.typing-modules`
 ///
 /// ## References
-/// - [PEP 536](https://peps.python.org/pep-0563/#runtime-annotation-resolution-and-type-checking)
+/// - [PEP 563: Runtime annotation resolution and `TYPE_CHECKING`](https://peps.python.org/pep-0563/#runtime-annotation-resolution-and-type-checking)
 #[violation]
 pub struct TypingOnlyFirstPartyImport {
     qualified_name: String,
@@ -146,7 +146,7 @@ impl Violation for TypingOnlyFirstPartyImport {
 /// - `lint.typing-modules`
 ///
 /// ## References
-/// - [PEP 536](https://peps.python.org/pep-0563/#runtime-annotation-resolution-and-type-checking)
+/// - [PEP 563: Runtime annotation resolution and `TYPE_CHECKING`](https://peps.python.org/pep-0563/#runtime-annotation-resolution-and-type-checking)
 #[violation]
 pub struct TypingOnlyThirdPartyImport {
     qualified_name: String,
@@ -221,7 +221,7 @@ impl Violation for TypingOnlyThirdPartyImport {
 /// - `lint.typing-modules`
 ///
 /// ## References
-/// - [PEP 536](https://peps.python.org/pep-0563/#runtime-annotation-resolution-and-type-checking)
+/// - [PEP 563: Runtime annotation resolution and `TYPE_CHECKING`](https://peps.python.org/pep-0563/#runtime-annotation-resolution-and-type-checking)
 #[violation]
 pub struct TypingOnlyStandardLibraryImport {
     qualified_name: String,