diff --git a/crates/ruff/src/rules/pydocstyle/rules/backslashes.rs b/crates/ruff/src/rules/pydocstyle/rules/backslashes.rs index 7bd2b326fd..a1ece3daae 100644 --- a/crates/ruff/src/rules/pydocstyle/rules/backslashes.rs +++ b/crates/ruff/src/rules/pydocstyle/rules/backslashes.rs @@ -7,6 +7,42 @@ use ruff_macros::{derive_message_formats, violation}; use crate::checkers::ast::Checker; use crate::docstrings::Docstring; +/// ## What it does +/// Checks for docstrings that include backslashes, but are not defined as +/// raw string literals. +/// +/// ## Why is this bad? +/// In Python, backslashes are typically used to escape characters in strings. +/// In raw strings (those prefixed with an `r`), however, backslashes are +/// treated as literal characters. +/// +/// [PEP 257](https://peps.python.org/pep-0257/#what-is-a-docstring) recommends +/// the use of raw strings (i.e., `r"""raw triple double quotes"""`) for +/// docstrings that include backslashes. The use of a raw string ensures that +/// any backslashes are treated as literal characters, and not as escape +/// sequences, which avoids confusion. +/// +/// ## Example +/// ```python +/// def foobar(): +/// """Docstring for foo\bar.""" +/// +/// +/// foobar.__doc__ # "Docstring for foar." +/// ``` +/// +/// Use instead: +/// ```python +/// def foobar(): +/// r"""Docstring for foo\bar.""" +/// +/// +/// foobar.__doc__ # "Docstring for foo\bar." +/// ``` +/// +/// ## References +/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/) +/// - [Python documentation: String and Bytes literals](https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals) #[violation] pub struct EscapeSequenceInDocstring; diff --git a/crates/ruff/src/rules/pydocstyle/rules/triple_quotes.rs b/crates/ruff/src/rules/pydocstyle/rules/triple_quotes.rs index 5cf020ce38..c1ccb64c99 100644 --- a/crates/ruff/src/rules/pydocstyle/rules/triple_quotes.rs +++ b/crates/ruff/src/rules/pydocstyle/rules/triple_quotes.rs @@ -4,6 +4,31 @@ use ruff_macros::{derive_message_formats, violation}; use crate::checkers::ast::Checker; use crate::docstrings::Docstring; +/// ## What it does +/// Checks for docstrings that use `'''triple single quotes'''` instead of +/// `"""triple double quotes"""`. +/// +/// ## Why is this bad? +/// [PEP 257](https://peps.python.org/pep-0257/#what-is-a-docstring) recommends +/// the use of `"""triple double quotes"""` for docstrings, to ensure +/// consistency. +/// +/// ## Example +/// ```python +/// def kos_root(): +/// '''Return the pathname of the KOS root directory.''' +/// ``` +/// +/// Use instead: +/// ```python +/// def kos_root(): +/// """Return the pathname of the KOS root directory.""" +/// ``` +/// +/// ## References +/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/) +/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html) +/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) #[violation] pub struct TripleSingleQuotes; diff --git a/crates/ruff/src/rules/ruff/rules/collection_literal_concatenation.rs b/crates/ruff/src/rules/ruff/rules/collection_literal_concatenation.rs index 86b51129d3..367c4ee026 100644 --- a/crates/ruff/src/rules/ruff/rules/collection_literal_concatenation.rs +++ b/crates/ruff/src/rules/ruff/rules/collection_literal_concatenation.rs @@ -37,7 +37,7 @@ use crate::registry::AsRule; /// /// ## References /// - [PEP 448 – Additional Unpacking Generalizations](https://peps.python.org/pep-0448/) -/// - [Python docs: Sequence Types — `list`, `tuple`, `range`](https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range) +/// - [Python documentation: Sequence Types — `list`, `tuple`, `range`](https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range) #[violation] pub struct CollectionLiteralConcatenation { expr: String, diff --git a/scripts/check_docs_formatted.py b/scripts/check_docs_formatted.py index 7256f28c7c..0c2680460c 100755 --- a/scripts/check_docs_formatted.py +++ b/scripts/check_docs_formatted.py @@ -52,6 +52,7 @@ KNOWN_FORMATTING_VIOLATIONS = [ "shebang-leading-whitespace", "too-few-spaces-before-inline-comment", "trailing-comma-on-bare-tuple", + "triple-single-quotes", "unexpected-indentation-comment", "unicode-kind-prefix", "unnecessary-class-parentheses",