From 9cd1bf9c034bed50747ea0ff26d13f25f6d7a13f Mon Sep 17 00:00:00 2001
From: Nuno Mendes <98030270+nm-remarkable@users.noreply.github.com>
Date: Wed, 8 Feb 2023 17:04:31 +0100
Subject: [PATCH] doc: add documentation for TRY002 (#2655)

---
 README.md                                     |  2 +-
 .../tryceratops/rules/raise_vanilla_class.rs  | 40 +++++++++++++++++
 docs/rules/raise-vanilla-class.md             | 44 +++++++++++++++++++
 docs/rules/raise_vanilla_class.md             | 38 ++++++++++++++++
 4 files changed, 123 insertions(+), 1 deletion(-)
 create mode 100644 docs/rules/raise-vanilla-class.md
 create mode 100644 docs/rules/raise_vanilla_class.md

diff --git a/README.md b/README.md
index f5631da7e9..779d19dae8 100644
--- a/README.md
+++ b/README.md
@@ -1368,7 +1368,7 @@ For more, see [tryceratops](https://pypi.org/project/tryceratops/1.1.0/) on PyPI
 
 | Code | Name | Message | Fix |
 | ---- | ---- | ------- | --- |
-| TRY002 | raise-vanilla-class | Create your own exception |  |
+| [TRY002](https://github.com/charliermarsh/ruff/blob/main/docs/rules/raise-vanilla-class.md) | [raise-vanilla-class](https://github.com/charliermarsh/ruff/blob/main/docs/rules/raise-vanilla-class.md) | Create your own exception |  |
 | TRY003 | raise-vanilla-args | Avoid specifying long messages outside the exception class |  |
 | TRY004 | prefer-type-error | Prefer `TypeError` exception for invalid type | 🛠 |
 | TRY200 | reraise-no-cause | Use `raise from` to specify exception cause |  |
diff --git a/crates/ruff/src/rules/tryceratops/rules/raise_vanilla_class.rs b/crates/ruff/src/rules/tryceratops/rules/raise_vanilla_class.rs
index 751659ca25..ed9a5befc9 100644
--- a/crates/ruff/src/rules/tryceratops/rules/raise_vanilla_class.rs
+++ b/crates/ruff/src/rules/tryceratops/rules/raise_vanilla_class.rs
@@ -7,6 +7,46 @@ use crate::registry::Diagnostic;
 use crate::violation::Violation;
 
 define_violation!(
+    /// ### What it does
+    /// Checks for code that raises `Exception` directly.
+    ///
+    /// ### Why is this bad?
+    /// Handling such exceptions requires the use of `except Exception`, which
+    /// captures _any_ raised exception, including failed assertions,
+    /// division by zero, and more.
+    ///
+    /// Prefer to raise your own exception, or a more specific built-in
+    /// exception, so that you can avoid over-capturing exceptions that you
+    /// don't intend to handle.
+    ///
+    /// ### Example
+    /// ```py
+    /// def main_function():
+    ///     if not cond:
+    ///         raise Exception()
+    /// def consumer_func():
+    ///     try:
+    ///         do_step()
+    ///         prepare()
+    ///         main_function()
+    ///     except Exception:
+    ///         logger.error("Oops")
+    /// ```
+    ///
+    /// Use instead:
+    /// ```py
+    /// def main_function():
+    ///     if not cond:
+    ///         raise CustomException()
+    /// def consumer_func():
+    ///     try:
+    ///         do_step()
+    ///         prepare()
+    ///         main_function()
+    ///     except CustomException:
+    ///         logger.error("Main function failed")
+    ///     except Exception:
+    ///         logger.error("Oops")
     pub struct RaiseVanillaClass;
 );
 impl Violation for RaiseVanillaClass {
diff --git a/docs/rules/raise-vanilla-class.md b/docs/rules/raise-vanilla-class.md
new file mode 100644
index 0000000000..60853d08a9
--- /dev/null
+++ b/docs/rules/raise-vanilla-class.md
@@ -0,0 +1,44 @@
+# raise-vanilla-class (TRY002)
+
+Derived from the **tryceratops** linter.
+
+### What it does
+Checks for code that raises `Exception` directly.
+
+### Why is this bad?
+Handling such exceptions requires the use of `except Exception`, which
+captures _any_ raised exception, including failed assertions,
+division by zero, and more.
+
+Prefer to raise your own exception, or a more specific built-in
+exception, so that you can avoid over-capturing exceptions that you
+don't intend to handle.
+
+### Example
+```py
+def main_function():
+    if not cond:
+        raise Exception()
+def consumer_func():
+    try:
+        do_step()
+        prepare()
+        main_function()
+    except Exception:
+        logger.error("Oops")
+```
+
+Use instead:
+```py
+def main_function():
+    if not cond:
+        raise CustomException()
+def consumer_func():
+    try:
+        do_step()
+        prepare()
+        main_function()
+    except CustomException:
+        logger.error("Main function failed")
+    except Exception:
+        logger.error("Oops")
\ No newline at end of file
diff --git a/docs/rules/raise_vanilla_class.md b/docs/rules/raise_vanilla_class.md
new file mode 100644
index 0000000000..dbfb2c35c7
--- /dev/null
+++ b/docs/rules/raise_vanilla_class.md
@@ -0,0 +1,38 @@
+# raise-vanilla-class (TRY002)
+Derived from the **tryceratops** linter.
+
+### What it does
+Checks for bare exceptions.
+
+## Why is this bad?
+It's hard to capture generic exceptions making it hard for handling specific scenarios.
+
+## Example
+```py
+def main_function():
+    if not cond:
+        raise Exception()
+def consumer_func():
+    try:
+        do_step()
+         prepare()
+        main_function()
+    except Exception:
+        logger.error("I have no idea what went wrong!!")
+```
+
+## How it should be
+```py
+def main_function():
+    if not cond:
+        raise CustomException()
+def consumer_func():
+    try:
+        do_step()
+        prepare()
+        main_function()
+    except CustomException:
+        logger.error("Main function failed")
+    except Exception:
+        logger.error("I have no idea what went wrong!!")
+```