From 7b6e55a2e0e5f5ec661bae116e39e7d39f4753d3 Mon Sep 17 00:00:00 2001
From: Tom Kuson <tjkuson@mailbox.org>
Date: Wed, 5 Apr 2023 18:30:25 +0100
Subject: [PATCH] Add documentation for `flake8-type-checking` (#3886)

---
 .../rules/typing_only_runtime_import.rs       | 105 ++++++++++++++++++
 1 file changed, 105 insertions(+)

diff --git a/crates/ruff/src/rules/flake8_type_checking/rules/typing_only_runtime_import.rs b/crates/ruff/src/rules/flake8_type_checking/rules/typing_only_runtime_import.rs
index 979ecbad19..7c13715c0c 100644
--- a/crates/ruff/src/rules/flake8_type_checking/rules/typing_only_runtime_import.rs
+++ b/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,