From 0bfdb15ecfa5e143c2d945b0db48e3694976c3b9 Mon Sep 17 00:00:00 2001
From: Tom Kuson <mail@tjkuson.me>
Date: Mon, 18 Sep 2023 18:33:15 +0100
Subject: [PATCH] Add documentation to `pass-statement-stub-body` (#7496)

## Summary

Add documentation to `pass-statement-stub-body` (`PYI009`) rule. Related
to #2646.

## Test Plan

`python scripts/check_docs_formatted.py`
---
 .../rules/pass_statement_stub_body.rs         | 20 +++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/crates/ruff/src/rules/flake8_pyi/rules/pass_statement_stub_body.rs b/crates/ruff/src/rules/flake8_pyi/rules/pass_statement_stub_body.rs
index e51b289808..3dd8f13b86 100644
--- a/crates/ruff/src/rules/flake8_pyi/rules/pass_statement_stub_body.rs
+++ b/crates/ruff/src/rules/flake8_pyi/rules/pass_statement_stub_body.rs
@@ -6,6 +6,26 @@ use ruff_text_size::Ranged;
 use crate::checkers::ast::Checker;
 use crate::registry::Rule;
 
+/// ## What it does
+/// Checks for `pass` statements in empty stub bodies.
+///
+/// ## Why is this bad?
+/// For consistency, empty stub bodies should contain `...` instead of `pass`.
+///
+/// Additionally, an ellipsis better conveys the intent of the stub body (that
+/// the body has been implemented, but has been intentionally left blank to
+/// document the interface).
+///
+/// ## Example
+/// ```python
+/// def foo(bar: int) -> list[int]:
+///     pass
+/// ```
+///
+/// Use instead:
+/// ```python
+/// def foo(bar: int) -> list[int]: ...
+/// ```
 #[violation]
 pub struct PassStatementStubBody;