From 2d89df7f6764580a449e8147fc0bcf97c758afce Mon Sep 17 00:00:00 2001
From: Richard Feldman <oss@rtfeldman.com>
Date: Thu, 25 Mar 2021 22:49:50 -0400
Subject: [PATCH] Improve some docs

---
 compiler/builtins/docs/Bool.roc | 13 ++++++-------
 compiler/builtins/docs/Num.roc  | 32 ++++++++++++++++----------------
 compiler/builtins/docs/Str.roc  |  6 +++---
 3 files changed, 25 insertions(+), 26 deletions(-)

diff --git a/compiler/builtins/docs/Bool.roc b/compiler/builtins/docs/Bool.roc
index 1c3a142200..601a3d491f 100644
--- a/compiler/builtins/docs/Bool.roc
+++ b/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`
 ##
diff --git a/compiler/builtins/docs/Num.roc b/compiler/builtins/docs/Num.roc
index 5f29271f76..9d8ef2104d 100644
--- a/compiler/builtins/docs/Num.roc
+++ 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
-U8 : Int @U8
-U16 : Int @U16
-I16 : Int @I16
-U32 : Int @U32
-I32 : Int @I32
-I64 : Int @I64
-U64 : Int @U64
-I128 : Int @I128
-U128 : Int @U128
-Ilen : Int @Ilen
-Nat : Int @Nat
+I8 : Int [ @I8 ]
+U8 : Int [ @U8 ]
+U16 : Int [ @U16 ]
+I16 : Int [ @I16 ]
+U32 : Int [ @U32 ]
+I32 : Int [ @I32 ]
+I64 : Int [ @I64 ]
+U64 : Int [ @U64 ]
+I128 : Int [ @I128 ]
+U128 : Int [ @U128 ]
+Ilen : Int [ @Ilen ]
+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
 
diff --git a/compiler/builtins/docs/Str.roc b/compiler/builtins/docs/Str.roc
index 54920bd56e..69b46ef348 100644
--- a/compiler/builtins/docs/Str.roc
+++ b/compiler/builtins/docs/Str.roc
@@ -1,7 +1,7 @@
-interface Str2
-    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 ]
+interface Str
+    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.