Improve excessive bools docs (#17080)

Improve the `fn_params_excessive_bools` docs to better explain why
boolean
parameters hurt call-site readability and to describe the main
replacement
patterns: enums for mode selection, separate named operations for
distinct
behaviors, and structs/options types for grouped flags.

This also documents that `max-fn-params-bools = 0` is valid and lints
any
function with a bool parameter.

changelog: [fn_params_excessive_bools]: improve documentation

Author: samueltardieu

book/src/lint_configuration.md

@@ -780,7 +780,8 @@ be filtering for common types.
 
 
 ## `max-fn-params-bools`
-The maximum number of bool parameters a function can have
+The maximum number of bool parameters a function can have.
+Use `0` to lint on any function with a bool parameter.
 
 **Default Value:** `3`
 

clippy_config/src/conf.rs

@@ -713,7 +713,8 @@ define_Conf! {
     /// be filtering for common types.
     #[lints(manual_let_else)]
     matches_for_let_else: MatchLintBehaviour = MatchLintBehaviour::WellKnownTypes,
-    /// The maximum number of bool parameters a function can have
+    /// The maximum number of bool parameters a function can have.
+    /// Use `0` to lint on any function with a bool parameter.
     #[lints(fn_params_excessive_bools)]
     max_fn_params_bools: u64 = 3,
     /// The maximum size of a file included via `include_bytes!()` or `include_str!()`, in bytes

clippy_lints/src/excessive_bools.rs

@@ -11,35 +11,51 @@ use rustc_span::def_id::LocalDefId;
 
 declare_clippy_lint! {
     /// ### What it does
-    /// Checks for excessive use of
-    /// bools in function definitions.
+    /// Checks for excessive use of bools in function declarations.
     ///
     /// ### Why is this bad?
-    /// Calls to such functions
-    /// are confusing and error prone, because it's
-    /// hard to remember argument order and you have
-    /// no type system support to back you up. Using
-    /// two-variant enums instead of bools often makes
-    /// API easier to use.
+    /// Boolean parameters obscure meaning at the call site. The reader has to
+    /// remember what each `true` or `false` means and which position each flag
+    /// belongs in, with no help from the type system.
+    ///
+    /// The best replacement depends on what role the bool plays:
+    ///
+    /// - Use a two-variant enum when one parameter selects a mode.
+    /// - Split one function into two named operations when the choices are
+    ///   distinct actions.
+    /// - Group multiple related flags into a struct or options type when they
+    ///   travel together.
+    /// - Move the setting onto `self` or an existing config/context parameter
+    ///   when it is really part of the surrounding state.
+    ///
+    /// This optimizes for readability of the calling code, which future readers
+    /// encounter more often than the function declaration.
+    ///
+    /// The `max-fn-params-bools` configuration accepts `0`, which lints on any
+    /// function with a bool parameter.
     ///
     /// ### Example
     /// ```rust,ignore
-    /// fn f(is_round: bool, is_hot: bool) { ... }
+    /// fn render_document(show_hidden: bool, is_draft: bool) { ... }
     /// ```
     ///
     /// Use instead:
     /// ```rust,ignore
-    /// enum Shape {
-    ///     Round,
-    ///     Spiky,
+    /// enum Visibility {
+    ///     ShowHidden,
+    ///     HideHidden,
     /// }
     ///
-    /// enum Temperature {
-    ///     Hot,
-    ///     IceCold,
+    /// enum DocumentKind {
+    ///     Draft,
+    ///     Final,
     /// }
     ///
-    /// fn f(shape: Shape, temperature: Temperature) { ... }
+    /// fn render_document(visibility: Visibility, kind: DocumentKind) { ... }
+    ///
+    /// // or split the operation when the choices are distinct
+    /// fn render_draft() { ... }
+    /// fn render_final() { ... }
     /// ```
     #[clippy::version = "1.43.0"]
     pub FN_PARAMS_EXCESSIVE_BOOLS,