Improve documentation for overlong-line rules (#5260)

Closes https://github.com/astral-sh/ruff/issues/5248.

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);
 

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);