From 0aa21277c64d60dcf0819cf5dfa2232687ec764d Mon Sep 17 00:00:00 2001
From: Charlie Marsh <charlie.r.marsh@gmail.com>
Date: Wed, 21 Jun 2023 13:02:20 -0400
Subject: [PATCH] Improve documentation for overlong-line rules (#5260)

Closes https://github.com/astral-sh/ruff/issues/5248.
---
 .../pycodestyle/rules/doc_line_too_long.rs    | 23 ++++++++++++++++++-
 .../rules/pycodestyle/rules/line_too_long.rs  | 16 ++++++++++++-
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/crates/ruff/src/rules/pycodestyle/rules/doc_line_too_long.rs b/crates/ruff/src/rules/pycodestyle/rules/doc_line_too_long.rs
index 68890d0235..7c047ab120 100644
--- a/crates/ruff/src/rules/pycodestyle/rules/doc_line_too_long.rs
+++ b/crates/ruff/src/rules/pycodestyle/rules/doc_line_too_long.rs
@@ -10,7 +10,21 @@ use crate::settings::Settings;
 ///
 /// ## Why is this bad?
 /// For flowing long blocks of text (docstrings or comments), overlong lines
-/// can hurt readability.
+/// can hurt readability. [PEP 8], for example, recommends that such lines be
+/// limited to 72 characters.
+///
+/// In the context of this rule, a "doc line" is defined as a line consisting
+/// of either a standalone comment or a standalone string, like a docstring.
+///
+/// In the interest of pragmatism, this rule makes a few exceptions when
+/// determining whether a line is overlong. Namely, it ignores lines that
+/// consist of a single "word" (i.e., without any whitespace between its
+/// characters), and lines that end with a URL (as long as the URL starts
+/// before the line-length threshold).
+///
+/// If `pycodestyle.ignore_overlong_task_comments` is `true`, this rule will
+/// also ignore comments that start with any of the specified `task-tags`
+/// (e.g., `# TODO:`).
 ///
 /// ## Example
 /// ```python
@@ -26,6 +40,13 @@ use crate::settings::Settings;
 ///     Duis auctor purus ut ex fermentum, at maximus est hendrerit.
 ///     """
 /// ```
+///
+///
+/// ## Options
+/// - `task-tags`
+/// - `pycodestyle.ignore-overlong-task-comments`
+///
+/// [PEP 8]: https://peps.python.org/pep-0008/#maximum-line-length
 #[violation]
 pub struct DocLineTooLong(pub usize, pub usize);
 
diff --git a/crates/ruff/src/rules/pycodestyle/rules/line_too_long.rs b/crates/ruff/src/rules/pycodestyle/rules/line_too_long.rs
index 6cb228239b..780906c598 100644
--- a/crates/ruff/src/rules/pycodestyle/rules/line_too_long.rs
+++ b/crates/ruff/src/rules/pycodestyle/rules/line_too_long.rs
@@ -9,7 +9,18 @@ use crate::settings::Settings;
 /// Checks for lines that exceed the specified maximum character length.
 ///
 /// ## Why is this bad?
-/// Overlong lines can hurt readability.
+/// Overlong lines can hurt readability. [PEP 8], for example, recommends
+/// limiting lines to 79 characters.
+///
+/// In the interest of pragmatism, this rule makes a few exceptions when
+/// determining whether a line is overlong. Namely, it ignores lines that
+/// consist of a single "word" (i.e., without any whitespace between its
+/// characters), and lines that end with a URL (as long as the URL starts
+/// before the line-length threshold).
+///
+/// If `pycodestyle.ignore_overlong_task_comments` is `true`, this rule will
+/// also ignore comments that start with any of the specified `task-tags`
+/// (e.g., `# TODO:`).
 ///
 /// ## Example
 /// ```python
@@ -26,6 +37,9 @@ use crate::settings::Settings;
 ///
 /// ## Options
 /// - `task-tags`
+/// - `pycodestyle.ignore-overlong-task-comments`
+///
+/// [PEP 8]: https://peps.python.org/pep-0008/#maximum-line-length
 #[violation]
 pub struct LineTooLong(pub usize, pub usize);