Add remaining pep8-naming docs (#4149)

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,

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,

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,