Add pygrep-hooks documentation (astral-sh#4131)

Author: tjkuson

_typos.toml

@@ -6,3 +6,4 @@ trivias = "trivias"
 hel = "hel"
 whos = "whos"
 spawnve = "spawnve"
+ned = "ned"

crates/ruff/src/rules/pygrep_hooks/rules/blanket_noqa.rs

@@ -6,6 +6,29 @@ use ruff_diagnostics::{Diagnostic, Violation};
 use ruff_macros::{derive_message_formats, violation};
 use ruff_python_ast::newlines::Line;
 
+/// ## What it does
+/// Check for `noqa` annotations that suppress all diagnostics, as opposed to
+/// targeting specific diagnostics.
+///
+/// ## Why is this bad?
+/// Suppressing all diagnostics can hide issues in the code.
+///
+/// Blanket `noqa` annotations are also more difficult to interpret and
+/// maintain, as the annotation does not clarify which diagnostics are intended
+/// to be suppressed.
+///
+/// ## Example
+/// ```python
+/// from .base import *  # noqa
+/// ```
+///
+/// Use instead:
+/// ```python
+/// from .base import *  # noqa: F403
+/// ```
+///
+/// ## References
+/// - [Ruff documentation](https://beta.ruff.rs/docs/configuration/#error-suppression)
 #[violation]
 pub struct BlanketNOQA;
 

crates/ruff/src/rules/pygrep_hooks/rules/blanket_type_ignore.rs

@@ -7,6 +7,29 @@ use ruff_diagnostics::{Diagnostic, Violation};
 use ruff_macros::{derive_message_formats, violation};
 use ruff_python_ast::newlines::Line;
 
+/// ## What it does
+/// Check for `type: ignore` annotations that suppress all type warnings, as
+/// opposed to targeting specific type warnings.
+///
+/// ## Why is this bad?
+/// Suppressing all warnings can hide issues in the code.
+///
+/// Blanket `type: ignore` annotations are also more difficult to interpret and
+/// maintain, as the annotation does not clarify which warnings are intended
+/// to be suppressed.
+///
+/// ## Example
+/// ```python
+/// from foo import secrets  # type: ignore
+/// ```
+///
+/// Use instead:
+/// ```python
+/// from foo import secrets  # type: ignore[attr-defined]
+/// ```
+///
+/// ## References
+/// - [mypy](https://mypy.readthedocs.io/en/stable/common_issues.html#spurious-errors-and-locally-silencing-the-checker)
 #[violation]
 pub struct BlanketTypeIgnore;
 

crates/ruff/src/rules/pygrep_hooks/rules/deprecated_log_warn.rs

@@ -5,6 +5,31 @@ use ruff_macros::{derive_message_formats, violation};
 
 use crate::checkers::ast::Checker;
 
+/// ## What it does
+/// Check for usages of the deprecated `warn` method from the `logging` module.
+///
+/// ## Why is this bad?
+/// The `warn` method is deprecated. Use `warning` instead.
+///
+/// ## Example
+/// ```python
+/// import logging
+///
+///
+/// def foo():
+///     logging.warn("Something happened")
+/// ```
+///
+/// Use instead:
+/// ```python
+/// import logging
+///
+/// def foo():
+///     logging.warning("Something happened")
+/// ```
+///
+/// ## References
+/// - [Python documentation](https://docs.python.org/3/library/logging.html#logging.Logger.warning)
 #[violation]
 pub struct DeprecatedLogWarn;
 

crates/ruff/src/rules/pygrep_hooks/rules/no_eval.rs

@@ -5,6 +5,29 @@ use ruff_macros::{derive_message_formats, violation};
 
 use crate::checkers::ast::Checker;
 
+/// ## What it does
+/// Checks for usages of the builtin `eval()` function.
+///
+/// ## Why is this bad?
+/// The `eval()` function is insecure as it enables arbitrary code execution.
+///
+/// ## Example
+/// ```python
+/// def foo():
+///     x = eval(input("Enter a number: "))
+///     ...
+/// ```
+///
+/// Use instead:
+/// ```python
+/// def foo():
+///     x = input("Enter a number: ")
+///     ...
+/// ```
+///
+/// ## References
+/// - [Python documentation](https://docs.python.org/3/library/functions.html#eval)
+/// - [_Eval really is dangerous_ by Ned Batchelder](https://nedbatchelder.com/blog/201206/eval_really_is_dangerous.html)
 #[violation]
 pub struct Eval;