bool/int

Author: dmcppcheck

man/checkers/bitwiseOnBoolean.md

@@ -1,7 +1,7 @@
 # bitwiseOnBoolean
 
 **Message**: Boolean expression 'x' is used in bitwise operation. Did you mean '&&'?<br/>
-**Category**: Code Quality<br/>
+**Category**: Readability<br/>
 **Severity**: Style (Inconclusive)<br/>
 **Language**: C/C++ (also applies to C's `_Bool`)
 
@@ -11,9 +11,20 @@
 
 ## Motivation
 
-`&`/`|` and `&&`/`||` look similar but behave very differently: the bitwise operators always evaluate
-both sides (no short-circuiting) and, for non-`bool` operands, work bit-by-bit rather than on the
-boolean truth value - so a stray single `&`/`|` where `&&`/`||` was meant can silently change behaviour.
+This checker is about readability. Readability is subjective - opinions differ about what is more
+readable. Please follow your own opinion.
+
+When both operands are `bool`, `&`/`|` on their `0`/`1` representation happens to produce the same
+truth value as `&&`/`||`, so this code usually still works correctly today. The main reason to flag it
+anyway is common practice: `&&`/`||` is the conventional, unambiguous way to write boolean logic in
+C/C++, while `&`/`|` is understood to mean bitwise work - so a stray single `&`/`|` reads as a likely
+typo even when it happens to be harmless. There is also one real behavioural difference: `&`/`|` always
+evaluates both operands, so if the other side has a side effect, using `&`/`|` instead of `&&`/`||`
+changes whether that side effect happens.
+
+When the *other* operand isn't itself boolean (e.g. an integer flag or count), `&`/`|` combines the
+boolean's `0`/`1` value with it bit-by-bit, which generally is **not** the same truth value `&&`/`||`
+would produce - in that case this points at an actual logic bug, not just a style preference.
 
 ## How to fix
 

man/checkers/comparisonOfBoolWithInvalidComparator.md

@@ -11,9 +11,12 @@ A boolean literal (`true`/`false`) is compared to something using `<`, `>`, `<=`
 
 ## Motivation
 
-`bool` only has two values, so ordering comparisons against a literal `true`/`false` don't express
-anything an equality comparison (`==`/`!=`) wouldn't say more clearly - and are easy to get backwards,
-since `false < true` is not always the intuitive direction a reader expects.
+`<`, `>`, `<=` and `>=` are well-defined against a `bool` literal (`false` is `0`, `true` is `1`), so
+this code already compiles and evaluates correctly - there is no functional problem to fix. The reason
+to flag it is readability: `bool` only has two values, so an ordering comparison against `true`/`false`
+says nothing that `==`/`!=` wouldn't say more directly, and it forces the reader to work out which of
+`false`/`true` is "smaller" instead of just reading the equality check. Preferring `==`/`!=` for
+two-valued types is the clearer, more idiomatic style.
 
 ## How to fix
 

man/checkers/comparisonOfFuncReturningBoolError.md

@@ -13,9 +13,12 @@ when both sides are.
 
 ## Motivation
 
-`bool` only has two values, so ordering its result doesn't express anything `==`/`!=` wouldn't say more
-clearly, and is easy to get backwards since `false < true` is not always the intuitive direction a
-reader expects.
+`<`, `>`, `<=` and `>=` are well-defined for `bool` results (`false` is `0`, `true` is `1`), so this code
+already compiles and evaluates correctly - there is no functional problem to fix. The reason to flag it
+is readability: `bool` only has two values, so ordering the result of a bool-returning function says
+nothing that `==`/`!=` wouldn't say more directly, and it forces the reader to work out which of
+`false`/`true` is "smaller" instead of just reading the equality/logical check. Preferring `==`/`!=` (or
+plain `&&`/`!`) for two-valued results is the clearer, more idiomatic style.
 
 ## How to fix