From 8f61eae1e7ce732f78c9d4574ee684ae17f4aa77 Mon Sep 17 00:00:00 2001
From: Calum Young <32770960+calumy@users.noreply.github.com>
Date: Sat, 29 Apr 2023 20:13:10 +0100
Subject: [PATCH] Add remaining `pep8-naming` docs (#4149)

---
 .../rules/invalid_argument_name.rs            | 28 +++++++++++++
 .../mixed_case_variable_in_class_scope.rs     | 30 ++++++++++++++
 .../mixed_case_variable_in_global_scope.rs    | 40 +++++++++++++++++++
 3 files changed, 98 insertions(+)

diff --git a/crates/ruff/src/rules/pep8_naming/rules/invalid_argument_name.rs b/crates/ruff/src/rules/pep8_naming/rules/invalid_argument_name.rs
index 94d04aefe2be9..58b9ebf971d1a 100644
--- a/crates/ruff/src/rules/pep8_naming/rules/invalid_argument_name.rs
+++ b/crates/ruff/src/rules/pep8_naming/rules/invalid_argument_name.rs
@@ -3,6 +3,34 @@ use rustpython_parser::ast::Arg;
 use ruff_diagnostics::{Diagnostic, Violation};
 use ruff_macros::{derive_message_formats, violation};
 
+/// ## What it does
+/// Checks for argument names that do not follow the `snake_case` convention.
+///
+/// ## Why is this bad?
+/// [PEP 8] recommends that function names should be lower case and separated
+/// by underscores (also known as `snake_case`).
+///
+/// > Function names should be lowercase, with words separated by underscores
+/// as necessary to improve readability.
+/// >
+/// > Variable names follow the same convention as function names.
+/// >
+/// > mixedCase is allowed only in contexts where that’s already the
+/// prevailing style (e.g. threading.py), to retain backwards compatibility.
+///
+/// ## Example
+/// ```python
+/// def MY_FUNCTION():
+///    pass
+/// ```
+///
+/// Use instead:
+/// ```python
+/// def my_function():
+///    pass
+/// ```
+///
+/// [PEP 8]: https://peps.python.org/pep-0008/#function-and-method-arguments
 #[violation]
 pub struct InvalidArgumentName {
     pub name: String,
diff --git a/crates/ruff/src/rules/pep8_naming/rules/mixed_case_variable_in_class_scope.rs b/crates/ruff/src/rules/pep8_naming/rules/mixed_case_variable_in_class_scope.rs
index 1bd1c24cf9d1c..52cc00ce950e8 100644
--- a/crates/ruff/src/rules/pep8_naming/rules/mixed_case_variable_in_class_scope.rs
+++ b/crates/ruff/src/rules/pep8_naming/rules/mixed_case_variable_in_class_scope.rs
@@ -6,6 +6,36 @@ use ruff_macros::{derive_message_formats, violation};
 use crate::checkers::ast::Checker;
 use crate::rules::pep8_naming::helpers;
 
+/// ## What it does
+/// Checks for class variable names that follow the `mixedCase` convention.
+///
+/// ## Why is this bad?
+/// [PEP 8] recommends that variable names should be lower case and separated
+/// by underscores (also known as `snake_case`).
+///
+/// > Function names should be lowercase, with words separated by underscores
+/// as necessary to improve readability.
+/// >
+/// > Variable names follow the same convention as function names.
+/// >
+/// > mixedCase is allowed only in contexts where that’s already the
+/// prevailing style (e.g. threading.py), to retain backwards compatibility.
+///
+/// ## Example
+/// ```python
+/// class MyClass:
+///     myVariable = "hello"
+///     another_variable = "world"
+/// ```
+///
+/// Use instead:
+/// ```python
+/// class MyClass:
+///     my_variable = "hello"
+///     another_variable = "world"
+/// ```
+///
+/// [PEP 8]: https://peps.python.org/pep-0008/#function-and-method-arguments
 #[violation]
 pub struct MixedCaseVariableInClassScope {
     pub name: String,
diff --git a/crates/ruff/src/rules/pep8_naming/rules/mixed_case_variable_in_global_scope.rs b/crates/ruff/src/rules/pep8_naming/rules/mixed_case_variable_in_global_scope.rs
index 470f809f97064..f5b5f7d54eabd 100644
--- a/crates/ruff/src/rules/pep8_naming/rules/mixed_case_variable_in_global_scope.rs
+++ b/crates/ruff/src/rules/pep8_naming/rules/mixed_case_variable_in_global_scope.rs
@@ -6,6 +6,46 @@ use ruff_macros::{derive_message_formats, violation};
 use crate::checkers::ast::Checker;
 use crate::rules::pep8_naming::helpers;
 
+/// ## What it does
+/// Checks for global variable names that follow the `mixedCase` convention.
+///
+/// ## Why is this bad?
+/// [PEP 8] recommends that global variable names should be lower case and
+/// separated by underscores (also known as `snake_case`).
+///
+/// > ### Global Variable Names
+/// > (Let’s hope that these variables are meant for use inside one module
+/// only.) The conventions are about the same as those for functions.
+/// >
+/// > Modules that are designed for use via from M import * should use the
+/// __all__ mechanism to prevent exporting globals, or use the older
+/// convention of prefixing such globals with an underscore (which you might
+///want to do to indicate these globals are “module non-public”).
+/// >
+/// > ### Function and Variable Names
+/// > Function names should be lowercase, with words separated by underscores
+/// as necessary to improve readability.
+/// >
+/// > Variable names follow the same convention as function names.
+/// >
+/// > mixedCase is allowed only in contexts where that’s already the prevailing
+/// style (e.g. threading.py), to retain backwards compatibility.
+///
+/// ## Example
+/// ```python
+/// myVariable = "hello"
+/// another_variable = "world"
+/// yet_anotherVariable = "foo"
+/// ```
+///
+/// Use instead:
+/// ```python
+/// my_variable = "hello"
+/// another_variable = "world"
+/// yet_another_variable = "foo"
+/// ```
+///
+/// [PEP 8]: https://peps.python.org/pep-0008/#global-variable-names
 #[violation]
 pub struct MixedCaseVariableInGlobalScope {
     pub name: String,