From 8001a2f121966f37641cd59196d9e679e56a48ce Mon Sep 17 00:00:00 2001
From: Charlie Marsh <charlie.r.marsh@gmail.com>
Date: Mon, 17 Jul 2023 10:12:46 -0400
Subject: [PATCH] Expand convention documentation (#5819)

---
 crates/ruff/src/rules/pydocstyle/settings.rs | 26 ++++++++++++++++++++
 ruff.schema.json                             |  2 +-
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/crates/ruff/src/rules/pydocstyle/settings.rs b/crates/ruff/src/rules/pydocstyle/settings.rs
index 1ec4a9a7fc..56cdb7dca5 100644
--- a/crates/ruff/src/rules/pydocstyle/settings.rs
+++ b/crates/ruff/src/rules/pydocstyle/settings.rs
@@ -87,6 +87,32 @@ pub struct Options {
     )]
     /// Whether to use Google-style or NumPy-style conventions or the PEP257
     /// defaults when analyzing docstring sections.
+    ///
+    /// Enabling a convention will force-disable any rules that are not
+    /// included in the specified convention. As such, the intended use is
+    /// to enable a convention and then selectively disable any additional
+    /// rules on top of it.
+    ///
+    /// For example, to use Google-style conventions but avoid requiring
+    /// documentation for every function parameter:
+    ///
+    /// ```toml
+    /// [tool.ruff]
+    /// # Enable all `pydocstyle` rules, limiting to those that adhere to the
+    /// # Google convention via `convention = "google"`, below.
+    /// select = ["D"]
+    ///
+    /// # On top of the Google convention, disable `D417`, which requires
+    /// # documentation for every function parameter.
+    /// ignore = ["D417"]
+    ///
+    /// [tool.ruff.pydocstyle]
+    /// convention = "google"
+    /// ```
+    ///
+    /// As conventions force-disable all rules not included in the convention,
+    /// enabling _additional_ rules on top of a convention is currently
+    /// unsupported.
     pub convention: Option<Convention>,
     #[option(
         default = r#"[]"#,
diff --git a/ruff.schema.json b/ruff.schema.json
index 8732c73890..a20e05447c 100644
--- a/ruff.schema.json
+++ b/ruff.schema.json
@@ -1478,7 +1478,7 @@
       "type": "object",
       "properties": {
         "convention": {
-          "description": "Whether to use Google-style or NumPy-style conventions or the PEP257 defaults when analyzing docstring sections.",
+          "description": "Whether to use Google-style or NumPy-style conventions or the PEP257 defaults when analyzing docstring sections.\n\nEnabling a convention will force-disable any rules that are not included in the specified convention. As such, the intended use is to enable a convention and then selectively disable any additional rules on top of it.\n\nFor example, to use Google-style conventions but avoid requiring documentation for every function parameter:\n\n```toml [tool.ruff] # Enable all `pydocstyle` rules, limiting to those that adhere to the # Google convention via `convention = \"google\"`, below. select = [\"D\"]\n\n# On top of the Google convention, disable `D417`, which requires # documentation for every function parameter. ignore = [\"D417\"]\n\n[tool.ruff.pydocstyle] convention = \"google\" ```\n\nAs conventions force-disable all rules not included in the convention, enabling _additional_ rules on top of a convention is currently unsupported.",
           "anyOf": [
             {
               "$ref": "#/definitions/Convention"