T201/T203 Improve print/pprint docs (#18130)

Co-authored-by: Micha Reiser <micha@reiser.io>

crates/ruff_linter/src/rules/flake8_print/rules/print_call.rs

@@ -11,26 +11,42 @@ use crate::registry::AsRule;
 /// Checks for `print` statements.
 ///
 /// ## Why is this bad?
-/// `print` statements are useful in some situations (e.g., debugging), but
+/// `print` statements used for debugging should be omitted from production
-/// should typically be omitted from production code. `print` statements can
+/// code. They can lead the accidental inclusion of sensitive information in
-/// lead to the accidental inclusion of sensitive information in logs, and are
+/// logs, and are not configurable by clients, unlike `logging` statements.
-/// not configurable by clients, unlike `logging` statements.
+///
+/// `print` statements used to produce output as a part of a command-line
+/// interface program are not typically a problem.
 ///
 /// ## Example
 /// ```python
-/// def add_numbers(a, b):
+/// def sum_less_than_four(a, b):
-///     print(f"The sum of {a} and {b} is {a + b}")
+///     print(f"Calling sum_less_than_four")
-///     return a + b
+///     return a + b < 4
 /// ```
 ///
-/// Use instead:
+/// The automatic fix will remove the print statement entirely:
+///
 /// ```python
-/// def add_numbers(a, b):
+/// def sum_less_than_four(a, b):
-///     return a + b
+///     return a + b < 4
+/// ```
+///
+/// To keep the line for logging purposes, instead use something like:
+///
+/// ```python
+/// import logging
+///
+/// logging.basicConfig(level=logging.INFO)
+///
+///
+/// def sum_less_than_four(a, b):
+///     logging.debug("Calling sum_less_than_four")
+///     return a + b < 4
 /// ```
 ///
 /// ## Fix safety
-/// This rule's fix is marked as unsafe, as it may remove `print` statements
+/// This rule's fix is marked as unsafe, as it will remove `print` statements
 /// that are used beyond debugging purposes.
 #[derive(ViolationMetadata)]
 pub(crate) struct Print;
@@ -52,11 +68,13 @@ impl Violation for Print {
 /// Checks for `pprint` statements.
 ///
 /// ## Why is this bad?
-/// Like `print` statements, `pprint` statements are useful in some situations
+/// Like `print` statements, `pprint` statements used for debugging should
-/// (e.g., debugging), but should typically be omitted from production code.
+/// be omitted from production code. They can lead the accidental inclusion
-/// `pprint` statements can lead to the accidental inclusion of sensitive
+/// of sensitive information in logs, and are not configurable by clients,
-/// information in logs, and are not configurable by clients, unlike `logging`
+/// unlike `logging` statements.
-/// statements.
+///
+/// `pprint` statements used to produce output as a part of a command-line
+/// interface program are not typically a problem.
 ///
 /// ## Example
 /// ```python
@@ -77,7 +95,7 @@ impl Violation for Print {
 /// ```
 ///
 /// ## Fix safety
-/// This rule's fix is marked as unsafe, as it may remove `pprint` statements
+/// This rule's fix is marked as unsafe, as it will remove `pprint` statements
 /// that are used beyond debugging purposes.
 #[derive(ViolationMetadata)]
 pub(crate) struct PPrint;