Add documentation for flake8-type-checking (#3886)

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

@@ -9,6 +9,41 @@ use ruff_python_semantic::binding::{
 use crate::rules::isort::{categorize, ImportType};
 use crate::settings::Settings;
 
+/// ## What it does
+/// Checks for first-party imports that are only used for type annotations, but
+/// aren't defined in a type-checking block.
+///
+/// ## Why is this bad?
+/// Unused imports add a performance overhead at runtime, and risk creating
+/// import cycles.
+///
+/// ## Example
+/// ```python
+/// from __future__ import annotations
+///
+/// import A
+///
+///
+/// def foo(a: A) -> int:
+///     return len(a)
+/// ```
+///
+/// Use instead:
+/// ```python
+/// from __future__ import annotations
+///
+/// from typing import TYPE_CHECKING
+///
+/// if TYPE_CHECKING:
+///     import A
+///
+///
+/// def foo(a: A) -> int:
+///     return len(a)
+/// ```
+///
+/// ## References
+/// - [PEP 536](https://peps.python.org/pep-0563/#runtime-annotation-resolution-and-type-checking)
 #[violation]
 pub struct TypingOnlyFirstPartyImport {
     pub full_name: String,
@@ -24,6 +59,41 @@ impl Violation for TypingOnlyFirstPartyImport {
     }
 }
 
+/// ## What it does
+/// Checks for third-party imports that are only used for type annotations, but
+/// aren't defined in a type-checking block.
+///
+/// ## Why is this bad?
+/// Unused imports add a performance overhead at runtime, and risk creating
+/// import cycles.
+///
+/// ## Example
+/// ```python
+/// from __future__ import annotations
+///
+/// import pandas as pd
+///
+///
+/// def foo(df: pd.DataFrame) -> int:
+///     return len(df)
+/// ```
+///
+/// Use instead:
+/// ```python
+/// from __future__ import annotations
+///
+/// from typing import TYPE_CHECKING
+///
+/// if TYPE_CHECKING:
+///     import pandas as pd
+///
+///
+/// def foo(df: pd.DataFrame) -> int:
+///     return len(df)
+/// ```
+///
+/// ## References
+/// - [PEP 536](https://peps.python.org/pep-0563/#runtime-annotation-resolution-and-type-checking)
 #[violation]
 pub struct TypingOnlyThirdPartyImport {
     pub full_name: String,
@@ -39,6 +109,41 @@ impl Violation for TypingOnlyThirdPartyImport {
     }
 }
 
+/// ## What it does
+/// Checks for standard library imports that are only used for type
+/// annotations, but aren't defined in a type-checking block.
+///
+/// ## Why is this bad?
+/// Unused imports add a performance overhead at runtime, and risk creating
+/// import cycles.
+///
+/// ## Example
+/// ```python
+/// from __future__ import annotations
+///
+/// from pathlib import Path
+///
+///
+/// def foo(path: Path) -> str:
+///     return str(path)
+/// ```
+///
+/// Use instead:
+/// ```python
+/// /// from __future__ import annotations
+///
+/// from typing import TYPE_CHECKING
+///
+/// if TYPE_CHECKING:
+///     from pathlib import Path
+///
+///
+/// def foo(path: Path) -> str:
+///     return str(path)
+/// ```
+///
+/// ## References
+/// - [PEP 536](https://peps.python.org/pep-0563/#runtime-annotation-resolution-and-type-checking)
 #[violation]
 pub struct TypingOnlyStandardLibraryImport {
     pub full_name: String,