Merge pull request #4387 from lukewilliamboswell/std-lib-bool

updated docs for Bool.roc

crates/compiler/builtins/roc/Bool.roc

@@ -2,28 +2,34 @@ interface Bool
     exposes [Bool, Eq, true, false, and, or, not, isEq, isNotEq]
     imports []
 
-## A type that can be compared for total equality.
+## Defines a type that can be compared for total equality.
 ##
 ## Total equality means that all values of the type can be compared to each
 ## other, and two values `a`, `b` are identical if and only if `isEq a b` is
 ## `Bool.true`.
 ##
-## Not all types support total equality. For example, an [F32] or [F64] can
-## be a `NaN` ([not a number](https://en.wikipedia.org/wiki/NaN)), and the [IEEE-754](https://en.wikipedia.org/wiki/IEEE_754)
-## floating point standard specifies that two `NaN`s are never equal to each other.
+## Not all types support total equality. For example, [F32] and [F64] can
+## be a `NaN` ([Not a Number](https://en.wikipedia.org/wiki/NaN)), and the
+## [IEEE-754](https://en.wikipedia.org/wiki/IEEE_754) floating point standard
+## specifies that two `NaN`s are not equal.
 Eq has
-    ## Returns `Bool.true` if the two values are equal, and `Bool.false` otherwise.
+    ## Returns `Bool.true` if the input values are equal. This is
+    ## equivalent to the logic
+    ## [XNOR](https://en.wikipedia.org/wiki/Logical_equality) gate. The infix
+    ## operator `==` can be used as shorthand for `Bool.isEq`.
     ##
-    ## `a == b` is shorthand for `Bool.isEq a b`.
+    ## **Note** that when `isEq` is determined by the Roc compiler, values are
+    ## compared using structural equality. The rules for this are as follows:
     ##
-    ## When `isEq` is derived by the Roc compiler, values are compared via
-    ## structural equality. Structural equality works as follows:
-    ##
-    ## 1. Tags are equal if they have the same tag name, and also their contents (if any) are equal.
-    ## 2. Records are equal if all their fields are equal.
-    ## 3. Collections ([Str], [List], [Dict], and [Set]) are equal if they are the same length, and also all their corresponding elements are equal.
-    ## 4. [Num](Num#Num) values are equal if their numbers are equal, with one exception: if both arguments to `isEq` are *NaN*, then `isEq` returns `Bool.false`. See `Num.isNaN` for more about *NaN*.
-    ## 5. Functions can never be compared for structural equality. Roc cannot derive `isEq` for types that contain functions!
+    ## 1. Tags are equal if their name and also contents are equal.
+    ## 2. Records are equal if their fields are equal.
+    ## 3. The collections [Str], [List], [Dict], and [Set] are equal iff they
+    ## are the same length and their elements are equal.
+    ## 4. [Num] values are equal if their numbers are equal. However, if both
+    ## inputs are *NaN* then `isEq` returns `Bool.false`. Refer to `Num.isNaN`
+    ## for more detail.
+    ## 5. Functions cannot be compared for structural equality, therefore Roc
+    ## cannot derive `isEq` for types that contain functions.
     isEq : a, a -> Bool | a has Eq
 
 Bool := [True, False] has [Eq { isEq: boolIsEq }]
@@ -38,67 +44,67 @@ true = @Bool True
 false : Bool
 false = @Bool False
 
-## Returns `Bool.true` when given `Bool.true` and `Bool.true`, and `Bool.false` when either argument is `Bool.false`.
+## Returns `Bool.true` when both inputs are `Bool.true`. This is equivalent to
+## the logic [AND](https://en.wikipedia.org/wiki/Logical_conjunction)
+## gate. The infix operator `&&` can also be used as shorthand for
+## `Bool.and`.
 ##
-## `a && b` is shorthand for `Bool.and a b`
+##     expect (Bool.and Bool.true Bool.true) == Bool.true
+##     expect (Bool.true && Bool.true) == Bool.true
+##     expect (Bool.false && Bool.true) == Bool.false
+##     expect (Bool.true && Bool.false) == Bool.false
+##     expect (Bool.false && Bool.false) == Bool.false
 ##
-## >>> Bool.true && Bool.true
-##
-## >>> Bool.true && Bool.false
-##
-## >>> Bool.false && Bool.true
-##
-## >>> Bool.false && Bool.false
-##
-## ## Performance Notes
-##
-## In some languages, `&&` and `||` are special-cased in the compiler to skip
-## evaluating the expression after the operator under certain circumstances.
-## For example, in some languages, `enablePets && likesDogs user` would compile
-## to the equivalent of:
+## **Performance Note** that in Roc the `&&` and `||` work the same way as any
+## other function. However, in some languages `&&` and `||` are special-cased.
+## In these languages the compiler will skip evaluating the expression after the
+## first operator under certain circumstances. For example an expression like
+## `enablePets && likesDogs user` would compile to.
 ##
 ##     if enablePets then
 ##         likesDogs user
 ##     else
 ##         Bool.false
 ##
-## In Roc, however, `&&` and `||` are not special. They work the same way as
-## other functions. Conditionals like `if` and `when` have a performance cost,
-## and sometimes calling a function like `likesDogs user` can be faster across
-## the board than doing an `if` to decide whether to skip calling it.
-##
-## (Naturally, if you expect the `if` to improve performance, you can always add
-## one explicitly!)
+## Roc does not do this because conditionals like `if` and `when` have a
+## performance cost. Calling a function can sometimes be faster across the board
+## than doing an `if` to decide whether to skip calling it.
 and : Bool, Bool -> Bool
 
-## Returns `Bool.true` when given `Bool.true` for either argument, and `Bool.false` only when given `Bool.false` and `Bool.false`.
+## Returns `Bool.true` when either input is a `Bool.true`. This is equivalent to
+## the logic [OR](https://en.wikipedia.org/wiki/Logical_disjunction) gate.
+## The infix operator `||` can also be used as shorthand for `Bool.or`.
 ##
-## `a || b` is shorthand for `Bool.or a b`.
+##     expect (Bool.or Bool.false Bool.true) == Bool.true
+##     expect (Bool.true || Bool.true) == Bool.true
+##     expect (Bool.false || Bool.true) == Bool.true
+##     expect (Bool.true || Bool.false) == Bool.true
+##     expect (Bool.false || Bool.false) == Bool.false
 ##
-## >>> Bool.true || Bool.true
-##
-## >>> Bool.true || Bool.false
-##
-## >>> Bool.false || Bool.true
-##
-## >>> Bool.false || Bool.false
-##
-## ## Performance Notes
-##
-## In some languages, `&&` and `||` are special-cased in the compiler to skip
-## evaluating the expression after the operator under certain circumstances.
-## In Roc, this is not the case. See the performance notes for [Bool.and] for details.
+## **Performance Note** that in Roc the `&&` and `||` work the same way as any
+## other functions. However, in some languages `&&` and `||` are special-cased.
+## Refer to the note in `Bool.and` for more detail.
 or : Bool, Bool -> Bool
-# xor : Bool, Bool -> Bool # currently unimplemented
-## Returns `Bool.false` when given `Bool.true`, and vice versa.
+
+## Returns `Bool.false` when given `Bool.true`, and vice versa. This is
+## equivalent to the logic [NOT](https://en.wikipedia.org/wiki/Negation)
+## gate. The operator `!` can also be used as shorthand for `Bool.not`.
+##
+##     expect (Bool.not Bool.false) == Bool.true
+##     expect (!Bool.false) == Bool.true
 not : Bool -> Bool
 
-## Calls [isEq] on the given values, then calls [not] on the result.
+## This will call the function `Bool.isEq` on the inputs, and then `Bool.not`
+## on the result. The is equivalent to the logic
+## [XOR](https://en.wikipedia.org/wiki/Exclusive_or) gate. The infix operator
+## `!=` can also be used as shorthand for `Bool.isNotEq`.
 ##
-## `a != b` is shorthand for `Bool.isNotEq a b`
+## **Note** that `isNotEq` does not accept arguments whose types contain
+## functions.
 ##
-## Note that `isNotEq` takes `'val` instead of `val`, which means `isNotEq` does not
-## accept arguments whose types contain functions.
+##     expect (Bool.isNotEq Bool.false Bool.true) == Bool.true
+##     expect (Bool.false != Bool.false) == Bool.false
+##     expect "Apples" != "Oranges"
 isNotEq : a, a -> Bool | a has Eq
 isNotEq = \a, b -> structuralNotEq a b