Add docs

Author: charliermarsh

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

@@ -20,6 +20,10 @@ use super::helpers::is_empty_or_null_string;
 /// A `pytest.raises` context manager should only contain a single simple
 /// statement that raises the expected exception.
 ///
+/// In [preview], this rule allows `pytest.raises` bodies to contain `for`
+/// loops with empty bodies (e.g., `pass` or `...` statements), to test
+/// iterator behavior.
+///
 /// ## Example
 /// ```python
 /// import pytest
@@ -46,6 +50,8 @@ use super::helpers::is_empty_or_null_string;
 ///
 /// ## References
 /// - [`pytest` documentation: `pytest.raises`](https://docs.pytest.org/en/latest/reference/reference.html#pytest-raises)
+///
+/// [preview]: https://docs.astral.sh/ruff/preview/
 #[derive(ViolationMetadata)]
 pub(crate) struct PytestRaisesWithMultipleStatements;
 
@@ -209,8 +215,9 @@ pub(crate) fn complex_raises(
 
             match stmt {
                 Stmt::With(ast::StmtWith { body, .. }) => is_non_trivial_with_body(body),
-                // Allow function and class definitions to test decorators
+                // Allow function and class definitions to test decorators.
                 Stmt::ClassDef(_) | Stmt::FunctionDef(_) => false,
+                // Allow empty `for` loops to test iterators.
                 Stmt::For(ast::StmtFor { body, .. }) if in_preview => match &body[..] {
                     [Stmt::Pass(_)] => false,
                     [Stmt::Expr(ast::StmtExpr { value, .. })] => !value.is_ellipsis_literal_expr(),

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

@@ -20,6 +20,10 @@ use super::helpers::is_empty_or_null_string;
 /// A `pytest.warns` context manager should only contain a single
 /// simple statement that triggers the expected warning.
 ///
+/// In [preview], this rule allows `pytest.warns` bodies to contain `for`
+/// loops with empty bodies (e.g., `pass` or `...` statements), to test
+/// iterator behavior.
+///
 /// ## Example
 /// ```python
 /// import pytest
@@ -38,12 +42,14 @@ use super::helpers::is_empty_or_null_string;
 ///
 /// def test_foo_warns():
 ///     setup()
-///     with pytest.warning(Warning):
+///     with pytest.warns(Warning):
 ///         foo()
 /// ```
 ///
 /// ## References
 /// - [`pytest` documentation: `pytest.warns`](https://docs.pytest.org/en/latest/reference/reference.html#pytest-warns)
+///
+/// [preview]: https://docs.astral.sh/ruff/preview/
 #[derive(ViolationMetadata)]
 pub(crate) struct PytestWarnsWithMultipleStatements;
 
@@ -204,8 +210,9 @@ pub(crate) fn complex_warns(checker: &mut Checker, stmt: &Stmt, items: &[WithIte
 
             match stmt {
                 Stmt::With(ast::StmtWith { body, .. }) => is_non_trivial_with_body(body),
-                // Allow function and class definitions to test decorators
+                // Allow function and class definitions to test decorators.
                 Stmt::ClassDef(_) | Stmt::FunctionDef(_) => false,
+                // Allow empty `for` loops to test iterators.
                 Stmt::For(ast::StmtFor { body, .. }) if in_preview => match &body[..] {
                     [Stmt::Pass(_)] => false,
                     [Stmt::Expr(ast::StmtExpr { value, .. })] => !value.is_ellipsis_literal_expr(),