Document inherent bool op expr evaluation

Author: Havvy

src/expressions/operator-expr.md

@@ -164,10 +164,10 @@ for other types. Remember that signed integers are always represented using
 two's complement. The operands of all of these operators are evaluated in
 [value expression context][value expression] so are moved or copied.
 
-| Symbol | Integer     | `bool`      | Floating Point | Overloading Trait  |
-|--------|-------------|-------------|----------------|--------------------|
-| `-`    | Negation*   |             | Negation       | `std::ops::Neg`    |
-| `!`    | Bitwise NOT | Logical NOT |                | `std::ops::Not`    |
+| Symbol | Integer     | `bool`        | Floating Point | Overloading Trait  |
+|--------|-------------|-------------- |----------------|--------------------|
+| `-`    | Negation*   |               | Negation       | `std::ops::Neg`    |
+| `!`    | Bitwise NOT | [Logical NOT] |                | `std::ops::Not`    |
 
 \* Only for signed integer types.
 
@@ -202,18 +202,18 @@ types. Remember that signed integers are always represented using two's
 complement. The operands of all of these operators are evaluated in [value
 expression context][value expression] so are moved or copied.
 
-| Symbol | Integer                 | `bool`      | Floating Point | Overloading Trait  | Overloading Compound Assignment Trait |
-|--------|-------------------------|-------------|----------------|--------------------| ------------------------------------- |
-| `+`    | Addition                |             | Addition       | `std::ops::Add`    | `std::ops::AddAssign`                 |
-| `-`    | Subtraction             |             | Subtraction    | `std::ops::Sub`    | `std::ops::SubAssign`                 |
-| `*`    | Multiplication          |             | Multiplication | `std::ops::Mul`    | `std::ops::MulAssign`                 |
-| `/`    | Division*               |             | Division       | `std::ops::Div`    | `std::ops::DivAssign`                 |
-| `%`    | Remainder               |             | Remainder      | `std::ops::Rem`    | `std::ops::RemAssign`                 |
-| `&`    | Bitwise AND             | Logical AND |                | `std::ops::BitAnd` | `std::ops::BitAndAssign`              |
-| <code>&#124;</code> | Bitwise OR | Logical OR  |                | `std::ops::BitOr`  | `std::ops::BitOrAssign`               |
-| `^`    | Bitwise XOR             | Logical XOR |                | `std::ops::BitXor` | `std::ops::BitXorAssign`              |
-| `<<`   | Left Shift              |             |                | `std::ops::Shl`    | `std::ops::ShlAssign`                 |
-| `>>`   | Right Shift**           |             |                | `std::ops::Shr`    |  `std::ops::ShrAssign`                |
+| Symbol | Integer                 | `bool`        | Floating Point | Overloading Trait  | Overloading Compound Assignment Trait |
+|--------|-------------------------|---------------|----------------|--------------------| ------------------------------------- |
+| `+`    | Addition                |               | Addition       | `std::ops::Add`    | `std::ops::AddAssign`                 |
+| `-`    | Subtraction             |               | Subtraction    | `std::ops::Sub`    | `std::ops::SubAssign`                 |
+| `*`    | Multiplication          |               | Multiplication | `std::ops::Mul`    | `std::ops::MulAssign`                 |
+| `/`    | Division*               |               | Division       | `std::ops::Div`    | `std::ops::DivAssign`                 |
+| `%`    | Remainder               |               | Remainder      | `std::ops::Rem`    | `std::ops::RemAssign`                 |
+| `&`    | Bitwise AND             | [Logical AND] |                | `std::ops::BitAnd` | `std::ops::BitAndAssign`              |
+| <code>&#124;</code> | Bitwise OR | [Logical OR]  |                | `std::ops::BitOr`  | `std::ops::BitOrAssign`               |
+| `^`    | Bitwise XOR             | [Logical XOR] |                | `std::ops::BitXor` | `std::ops::BitXorAssign`              |
+| `<<`   | Left Shift              |               |                | `std::ops::Shl`    | `std::ops::ShlAssign`                 |
+| `>>`   | Right Shift**           |               |                | `std::ops::Shr`    |  `std::ops::ShrAssign`                |
 
 \* Integer division rounds towards zero.
 
@@ -522,6 +522,10 @@ dependency.
 
 [copies or moves]: ../expressions.md#moved-and-copied-types
 [dropping]: ../destructors.md
+[logical and]: ../types/boolean.md##logical-and
+[logical not]: ../types/boolean.md##logical-not
+[logical or]: ../types/boolean.md##logical-or
+[logical xor]: ../types/boolean.md##logical-xor
 [mutable]: ../expressions.md#mutability
 [place expression]: ../expressions.md#place-expressions-and-value-expressions
 [unit]: ../types/tuple.md

src/types/boolean.md

@@ -32,13 +32,79 @@ Like all primitives, the boolean type [implements][p-impl] the
 
 > **Note**: See the [standard library docs][std] for library operations.
 
+## Operations on boolean values
+
+<!-- This is washy wording --> When using certain operator expressions with a
+boolean type for its operands, they evaluate using the rules of [boolean logic].
+
+### Logical not
+
+| `b` | [`!b`][op-not] |
+|- | - |
+| `true` | `false` |
+| `false` | `true` |
+
+### Logical or
+
+| `a` | `b` | [<code>a &#124; b</code>][op-or] |
+|- | - | - |
+| `true` | `true` | `true` |
+| `true` | `false` | `true` |
+| `false` | `true` | `true` |
+| `false` | `false` | `false` |
+
+### Logical and
+
+| `a` | `b` | [`a & b`][op-and] |
+|- | - | - |
+| `true` | `true` | `true` |
+| `true` | `false` | `false` |
+| `false` | `true` | `false` |
+| `false` | `false` | `false` |
+
+### Logical xor
+
+| `a` | `b` | [`a ^ b`][op-xor] |
+|- | - | - |
+| `true` | `true` | `false` |
+| `true` | `false` | `true` |
+| `false` | `true` | `true` |
+| `false` | `false` | `false` |
+
+### Comparisons
+
+| `a` | `b` | [`a == b`][op-compare] |
+|- | - | - |
+| `true` | `true` | `true` |
+| `true` | `false` | `false` |
+| `false` | `true` | `false` |
+| `false` | `false` | `true` |
+
+| `a` | `b` | [`a > b`][op-compare] |
+|- | - | - |
+| `true` | `true` | `false` |
+| `true` | `false` | `true` |
+| `false` | `true` | `false` |
+| `false` | `false` | `false` |
+
+* `a != b` is the same as `!(a == b)`
+* `a >= b` is the same as `a == b | a > b`
+* `a < b` is the same as `!(a >= b)`
+* `a <= b` is the same as `a == b | a < b`
+
+[boolean logic]: https://en.wikipedia.org/wiki/Boolean_algebra
 [enumerated type]: enum.md
 [expressions]: ../expressions.md
 [if expressions]: ../expressions/if-expr.md#if-expressions
 [language prelude]: ../names/preludes.md#language-prelude
 [lazy]: ../expressions/operator-expr.md#lazy-boolean-operators
 [literal expression]: ../expressions/literal-expr.md
 [name]: ../names.md
+[op-and]: expressions/operator-expr.md#arithmetic-and-logical-binary-operators
+[op-compare]: ../expressions/operator-expr.md#comparison-operators
+[op-not]: ../expressions/operator-expr.md#negation-operators
+[op-or]: expressions/operator-expr.md#arithmetic-and-logical-binary-operators
+[op-xor]: expressions/operator-expr.md#arithmetic-and-logical-binary-operators
 [p-clone]: ../special-types-and-traits.md#clone
 [p-copy]: ../special-types-and-traits.md#copy
 [p-impl]: ../items/implementations.md