Improve some docs

compiler/builtins/docs/Bool.roc

@@ -1,11 +1,11 @@
-interface Bool2
+interface Bool
     exposes [ not, and, or, xor, isEq, isNotEq ]
     imports []
 
-## Returns #False when given #True, and vice versa.
+## Returns `False` when given `True`, and vice versa.
 not : [True, False] -> [True, False]
 
-## Returns #True when given #True and #True, and #False when either argument is #False.
+## Returns `True` when given `True` and `True`, and `False` when either argument is `False`.
 ##
 ## `a && b` is shorthand for `Bool.and a b`
 ##
@@ -39,7 +39,7 @@ not : [True, False] -> [True, False]
 and : Bool, Bool -> Bool
 
 
-## Returns #True when given #True for either argument, and #False only when given #False and #False.
+## Returns `True` when given `True` for either argument, and `False` only when given `False` and `False`.
 ##
 ## `a || b` is shorthand for `Bool.or a b`.
 ##
@@ -55,14 +55,13 @@ and : Bool, Bool -> Bool
 ##
 ## 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.
-## In Roc, this is not the case. See the performance notes for #Bool.and for details.
 or : Bool, Bool -> Bool
 
 ## Exclusive or
 xor : Bool, Bool -> Bool
 
-## Returns #True if the two values are *structurally equal*, and #False otherwise.
+## Returns `True` if the two values are *structurally equal*, and `False` otherwise.
 ##
 ## `a == b` is shorthand for `Bool.isEq a b`
 ##

compiler/builtins/docs/Num.roc

@@ -51,7 +51,7 @@ interface Num2
 ##
 ## In practice, these are rarely needed. It's most common to write
 ## number literals without any suffix.
-Num range : @Num range
+Num range : [ @Num range ]
 
 ## A fixed-size integer - that is, a number with no fractional component.
 ##
@@ -102,21 +102,21 @@ Num range : @Num range
 ## * Start by deciding if this integer should allow negative numbers, and choose signed or unsigned accordingly.
 ## * Next, think about the range of numbers you expect this number to hold. Choose the smallest size you will never expect to overflow, no matter the inputs your program receives. (Validating inputs for size, and presenting the user with an error if they are too big, can help guard against overflow.)
 ## * Finally, if a particular numeric calculation is running too slowly, you can try experimenting with other number sizes. This rarely makes a meaningful difference, but some processors can operate on different number sizes at different speeds.
-Int size : Num (@Int size)
+Int size : Num [ @Int size ]
 
 ## A signed 8-bit integer, ranging from -128 to 127
-I8 : Int @I8
+I8 : Int [ @I8 ]
-U8 : Int @U8
+U8 : Int [ @U8 ]
-U16 : Int @U16
+U16 : Int [ @U16 ]
-I16 : Int @I16
+I16 : Int [ @I16 ]
-U32 : Int @U32
+U32 : Int [ @U32 ]
-I32 : Int @I32
+I32 : Int [ @I32 ]
-I64 : Int @I64
+I64 : Int [ @I64 ]
-U64 : Int @U64
+U64 : Int [ @U64 ]
-I128 : Int @I128
+I128 : Int [ @I128 ]
-U128 : Int @U128
+U128 : Int [ @U128 ]
-Ilen : Int @Ilen
+Ilen : Int [ @Ilen ]
-Nat : Int @Nat
+Nat : Int [ @Nat ]
 
 ## A 64-bit signed integer. All number literals without decimal points are compatible with #Int values.
 ##
@@ -574,9 +574,9 @@ divRound : Int, Int -> Int
 
 ## Bitwise
 
-xor : Int -> Int -> Int
+xor : Int, Int -> Int
 
-and : Int -> Int -> Int
+and : Int, Int -> Int
 
 not : Int -> Int
 

compiler/builtins/docs/Str.roc

@@ -1,7 +1,7 @@
-interface Str2
+interface Str
-    exposes [ Str2, decimal, split, isEmpty, startsWith, endsWith, contains, anyGraphemes, allGraphemes, join, joinWith, padGraphemesStart, padGraphemesEnd, graphemes, reverseGraphemes, isCaseInsensitiveEq, isCaseInsensitiveNeq, walkGraphemes, isCapitalized, isAllUppercase, isAllLowercase, toUtf8, toUtf16, toUtf32, walkUtf8, walkUtf16, walkUtf32, walkRevUtf8, walkRevUtf16, walkRevUtf32 ]
+    exposes [ Str, decimal, split, isEmpty, startsWith, endsWith, contains, anyGraphemes, allGraphemes, join, joinWith, padGraphemesStart, padGraphemesEnd, graphemes, reverseGraphemes, isCaseInsensitiveEq, isCaseInsensitiveNeq, walkGraphemes, isCapitalized, isAllUppercase, isAllLowercase, toUtf8, toUtf16, toUtf32, walkUtf8, walkUtf16, walkUtf32, walkRevUtf8, walkRevUtf16, walkRevUtf32 ]
     imports []
-## Types
+## # Types
 
 ## Dealing with text is a deep topic, so by design, Roc's `Str` module sticks
 ## to the basics.