Document logger-objects setting in flake8-logging-format rules (#6832)

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

crates/ruff/src/rules/flake8_logging_format/violations.rs

@@ -21,6 +21,19 @@ use ruff_macros::{derive_message_formats, violation};
 /// As an alternative to `extra`, passing values as arguments to the logging
 /// method can also be used to defer string formatting until required.
 ///
+/// ## Known problems
+///
+/// This rule detects uses of the `logging` module via a heuristic.
+/// Specifically, it matches against:
+///
+/// - Uses of the `logging` module itself (e.g., `import logging; logging.info(...)`).
+/// - Uses of `flask.current_app.logger` (e.g., `from flask import current_app; current_app.logger.info(...)`).
+/// - Objects whose name starts with `log` or ends with `logger` or `logging`,
+///   when used in the same file in which they are defined (e.g., `logger = logging.getLogger(); logger.info(...)`).
+/// - Imported objects marked as loggers via the [`logger-objects`] setting, which can be
+///   used to enforce these rules against shared logger objects (e.g., `from module import logger; logger.info(...)`,
+///   when [`logger-objects`] is set to `["module.logger"]`).
+///
 /// ## Example
 /// ```python
 /// import logging
@@ -54,6 +67,9 @@ use ruff_macros::{derive_message_formats, violation};
 /// logging.info("%s - Something happened", user)
 /// ```
 ///
+/// ## Options
+/// - `logger-objects`
+///
 /// ## References
 /// - [Python documentation: `logging`](https://docs.python.org/3/library/logging.html)
 /// - [Python documentation: Optimization](https://docs.python.org/3/howto/logging.html#optimization)
@@ -89,6 +105,19 @@ impl Violation for LoggingStringFormat {
 /// As an alternative to `extra`, passing values as arguments to the logging
 /// method can also be used to defer string formatting until required.
 ///
+/// ## Known problems
+///
+/// This rule detects uses of the `logging` module via a heuristic.
+/// Specifically, it matches against:
+///
+/// - Uses of the `logging` module itself (e.g., `import logging; logging.info(...)`).
+/// - Uses of `flask.current_app.logger` (e.g., `from flask import current_app; current_app.logger.info(...)`).
+/// - Objects whose name starts with `log` or ends with `logger` or `logging`,
+///   when used in the same file in which they are defined (e.g., `logger = logging.getLogger(); logger.info(...)`).
+/// - Imported objects marked as loggers via the [`logger-objects`] setting, which can be
+///   used to enforce these rules against shared logger objects (e.g., `from module import logger; logger.info(...)`,
+///   when [`logger-objects`] is set to `["module.logger"]`).
+///
 /// ## Example
 /// ```python
 /// import logging
@@ -122,6 +151,9 @@ impl Violation for LoggingStringFormat {
 /// logging.info("%s - Something happened", user)
 /// ```
 ///
+/// ## Options
+/// - `logger-objects`
+///
 /// ## References
 /// - [Python documentation: `logging`](https://docs.python.org/3/library/logging.html)
 /// - [Python documentation: Optimization](https://docs.python.org/3/howto/logging.html#optimization)
@@ -156,6 +188,19 @@ impl Violation for LoggingPercentFormat {
 /// As an alternative to `extra`, passing values as arguments to the logging
 /// method can also be used to defer string formatting until required.
 ///
+/// ## Known problems
+///
+/// This rule detects uses of the `logging` module via a heuristic.
+/// Specifically, it matches against:
+///
+/// - Uses of the `logging` module itself (e.g., `import logging; logging.info(...)`).
+/// - Uses of `flask.current_app.logger` (e.g., `from flask import current_app; current_app.logger.info(...)`).
+/// - Objects whose name starts with `log` or ends with `logger` or `logging`,
+///   when used in the same file in which they are defined (e.g., `logger = logging.getLogger(); logger.info(...)`).
+/// - Imported objects marked as loggers via the [`logger-objects`] setting, which can be
+///   used to enforce these rules against shared logger objects (e.g., `from module import logger; logger.info(...)`,
+///   when [`logger-objects`] is set to `["module.logger"]`).
+///
 /// ## Example
 /// ```python
 /// import logging
@@ -189,6 +234,9 @@ impl Violation for LoggingPercentFormat {
 /// logging.info("%s - Something happened", user)
 /// ```
 ///
+/// ## Options
+/// - `logger-objects`
+///
 /// ## References
 /// - [Python documentation: `logging`](https://docs.python.org/3/library/logging.html)
 /// - [Python documentation: Optimization](https://docs.python.org/3/howto/logging.html#optimization)
@@ -222,6 +270,19 @@ impl Violation for LoggingStringConcat {
 /// As an alternative to `extra`, passing values as arguments to the logging
 /// method can also be used to defer string formatting until required.
 ///
+/// ## Known problems
+///
+/// This rule detects uses of the `logging` module via a heuristic.
+/// Specifically, it matches against:
+///
+/// - Uses of the `logging` module itself (e.g., `import logging; logging.info(...)`).
+/// - Uses of `flask.current_app.logger` (e.g., `from flask import current_app; current_app.logger.info(...)`).
+/// - Objects whose name starts with `log` or ends with `logger` or `logging`,
+///   when used in the same file in which they are defined (e.g., `logger = logging.getLogger(); logger.info(...)`).
+/// - Imported objects marked as loggers via the [`logger-objects`] setting, which can be
+///   used to enforce these rules against shared logger objects (e.g., `from module import logger; logger.info(...)`,
+///   when [`logger-objects`] is set to `["module.logger"]`).
+///
 /// ## Example
 /// ```python
 /// import logging
@@ -255,6 +316,9 @@ impl Violation for LoggingStringConcat {
 /// logging.info("%s - Something happened", user)
 /// ```
 ///
+/// ## Options
+/// - `logger-objects`
+///
 /// ## References
 /// - [Python documentation: `logging`](https://docs.python.org/3/library/logging.html)
 /// - [Python documentation: Optimization](https://docs.python.org/3/howto/logging.html#optimization)
@@ -276,6 +340,19 @@ impl Violation for LoggingFString {
 /// `logging.warning` and `logging.Logger.warning`, which are functionally
 /// equivalent.
 ///
+/// ## Known problems
+///
+/// This rule detects uses of the `logging` module via a heuristic.
+/// Specifically, it matches against:
+///
+/// - Uses of the `logging` module itself (e.g., `import logging; logging.info(...)`).
+/// - Uses of `flask.current_app.logger` (e.g., `from flask import current_app; current_app.logger.info(...)`).
+/// - Objects whose name starts with `log` or ends with `logger` or `logging`,
+///   when used in the same file in which they are defined (e.g., `logger = logging.getLogger(); logger.info(...)`).
+/// - Imported objects marked as loggers via the [`logger-objects`] setting, which can be
+///   used to enforce these rules against shared logger objects (e.g., `from module import logger; logger.info(...)`,
+///   when [`logger-objects`] is set to `["module.logger"]`).
+///
 /// ## Example
 /// ```python
 /// import logging
@@ -290,6 +367,9 @@ impl Violation for LoggingFString {
 /// logging.warning("Something happened")
 /// ```
 ///
+/// ## Options
+/// - `logger-objects`
+///
 /// ## References
 /// - [Python documentation: `logging.warning`](https://docs.python.org/3/library/logging.html#logging.warning)
 /// - [Python documentation: `logging.Logger.warning`](https://docs.python.org/3/library/logging.html#logging.Logger.warning)
@@ -320,6 +400,19 @@ impl AlwaysAutofixableViolation for LoggingWarn {
 /// the `LogRecord` constructor will raise a `KeyError` when the `LogRecord` is
 /// constructed.
 ///
+/// ## Known problems
+///
+/// This rule detects uses of the `logging` module via a heuristic.
+/// Specifically, it matches against:
+///
+/// - Uses of the `logging` module itself (e.g., `import logging; logging.info(...)`).
+/// - Uses of `flask.current_app.logger` (e.g., `from flask import current_app; current_app.logger.info(...)`).
+/// - Objects whose name starts with `log` or ends with `logger` or `logging`,
+///   when used in the same file in which they are defined (e.g., `logger = logging.getLogger(); logger.info(...)`).
+/// - Imported objects marked as loggers via the [`logger-objects`] setting, which can be
+///   used to enforce these rules against shared logger objects (e.g., `from module import logger; logger.info(...)`,
+///   when [`logger-objects`] is set to `["module.logger"]`).
+///
 /// ## Example
 /// ```python
 /// import logging
@@ -342,6 +435,9 @@ impl AlwaysAutofixableViolation for LoggingWarn {
 /// logging.info("Something happened", extra=dict(user=username))
 /// ```
 ///
+/// ## Options
+/// - `logger-objects`
+///
 /// ## References
 /// - [Python documentation: LogRecord attributes](https://docs.python.org/3/library/logging.html#logrecord-attributes)
 #[violation]
@@ -365,6 +461,19 @@ impl Violation for LoggingExtraAttrClash {
 /// `logging.exception`. Using `logging.exception` is more concise, more
 /// readable, and conveys the intent of the logging statement more clearly.
 ///
+/// ## Known problems
+///
+/// This rule detects uses of the `logging` module via a heuristic.
+/// Specifically, it matches against:
+///
+/// - Uses of the `logging` module itself (e.g., `import logging; logging.info(...)`).
+/// - Uses of `flask.current_app.logger` (e.g., `from flask import current_app; current_app.logger.info(...)`).
+/// - Objects whose name starts with `log` or ends with `logger` or `logging`,
+///   when used in the same file in which they are defined (e.g., `logger = logging.getLogger(); logger.info(...)`).
+/// - Imported objects marked as loggers via the [`logger-objects`] setting, which can be
+///   used to enforce these rules against shared logger objects (e.g., `from module import logger; logger.info(...)`,
+///   when [`logger-objects`] is set to `["module.logger"]`).
+///
 /// ## Example
 /// ```python
 /// import logging
@@ -385,6 +494,9 @@ impl Violation for LoggingExtraAttrClash {
 ///     logging.exception("Exception occurred")
 /// ```
 ///
+/// ## Options
+/// - `logger-objects`
+///
 /// ## References
 /// - [Python documentation: `logging.exception`](https://docs.python.org/3/library/logging.html#logging.exception)
 /// - [Python documentation: `exception`](https://docs.python.org/3/library/logging.html#logging.Logger.exception)
@@ -410,6 +522,19 @@ impl Violation for LoggingExcInfo {
 /// Passing `exc_info=True` to `logging.exception` calls is redundant, as is
 /// passing `exc_info=False` to `logging.error` calls.
 ///
+/// ## Known problems
+///
+/// This rule detects uses of the `logging` module via a heuristic.
+/// Specifically, it matches against:
+///
+/// - Uses of the `logging` module itself (e.g., `import logging; logging.info(...)`).
+/// - Uses of `flask.current_app.logger` (e.g., `from flask import current_app; current_app.logger.info(...)`).
+/// - Objects whose name starts with `log` or ends with `logger` or `logging`,
+///   when used in the same file in which they are defined (e.g., `logger = logging.getLogger(); logger.info(...)`).
+/// - Imported objects marked as loggers via the [`logger-objects`] setting, which can be
+///   used to enforce these rules against shared logger objects (e.g., `from module import logger; logger.info(...)`,
+///   when [`logger-objects`] is set to `["module.logger"]`).
+///
 /// ## Example
 /// ```python
 /// import logging
@@ -430,6 +555,9 @@ impl Violation for LoggingExcInfo {
 ///     logging.exception("Exception occurred")
 /// ```
 ///
+/// ## Options
+/// - `logger-objects`
+///
 /// ## References
 /// - [Python documentation: `logging.exception`](https://docs.python.org/3/library/logging.html#logging.exception)
 /// - [Python documentation: `exception`](https://docs.python.org/3/library/logging.html#logging.Logger.exception)