diff --git a/crates/compiler/builtins/roc/Box.roc b/crates/compiler/builtins/roc/Box.roc index 5bebae160a..53a45f760c 100644 --- a/crates/compiler/builtins/roc/Box.roc +++ b/crates/compiler/builtins/roc/Box.roc @@ -2,7 +2,7 @@ interface Box exposes [box, unbox] imports [] -## Allocate a value on the heap. Boxing is an expensive process as it copies +## Allocates a value on the heap. Boxing is an expensive process as it copies ## the value from the stack to the heap. This may provide a performance ## optimization for advanced use cases with large values. A platform may require ## that some values are boxed. diff --git a/crates/compiler/builtins/roc/List.roc b/crates/compiler/builtins/roc/List.roc index 265c18e415..baa1eedc24 100644 --- a/crates/compiler/builtins/roc/List.roc +++ b/crates/compiler/builtins/roc/List.roc @@ -72,7 +72,8 @@ interface List Num.{ Nat, Num, Int }, ] -## Types +## ## Types +## ## A sequential list of values. ## ``` ## [1, 2, 3] # a list of numbers diff --git a/crates/compiler/builtins/roc/Num.roc b/crates/compiler/builtins/roc/Num.roc index 3144939828..2b5dd9869c 100644 --- a/crates/compiler/builtins/roc/Num.roc +++ b/crates/compiler/builtins/roc/Num.roc @@ -233,7 +233,7 @@ Num range := range ## ## [I8] is a signed integer that takes up 8 bits. The `I` is for Integer, since ## integers in mathematics are signed by default. Because it has 8 bits just -## like [U8], it can store 256 numbers (still 2^16), but because it is signed, +## like [U8], it can store 256 numbers (still 2^8), but because it is signed, ## the range is different. Its 256 numbers range from -128 to 127. ## ## Here are some other examples: @@ -283,7 +283,7 @@ Num range := range ## general trade-offs are: ## ## * Larger integer sizes can represent a wider range of numbers. If you absolutely need to represent numbers in a certain range, make sure to pick an integer size that can hold them! -## * Smaller integer sizes take up less memory. This savings rarely matters in variables and function arguments, but the sizes of integers that you use in data structures can add up. This can also affect whether those data structures fit in [cache lines](https://en.wikipedia.org/wiki/CPU_cache#Cache_performance), which can be a performance bottleneck. +## * Smaller integer sizes take up less memory. These savings rarely matter in variables and function arguments, but the sizes of integers that you use in data structures can add up. This can also affect whether those data structures fit in [cache lines](https://en.wikipedia.org/wiki/CPU_cache#Cache_performance), which can be a performance bottleneck. ## * Certain CPUs work faster on some numeric sizes than others. If the CPU is taking too long to run numeric calculations, you may find a performance improvement by experimenting with numeric sizes that are larger than otherwise necessary. However, in practice, doing this typically degrades overall performance, so be careful to measure properly! ## ## Here are the different fixed size integer types: @@ -327,7 +327,7 @@ Num range := range ## ## A common use for [Nat] is to store the length ("len" for short) of a ## collection like a [List]. 64-bit systems can represent longer -## lists in memory than 32-bit systems can, which is why the length of a list +## lists in memory than 32-bit systems, which is why the length of a list ## is represented as a [Nat] in Roc. ## ## If any operation would result in an [Int] that is either too big @@ -647,7 +647,7 @@ isInfinite : Frac * -> Bool ## ``` isFinite : Frac * -> Bool -## Return the absolute value of the number. +## Returns the absolute value of the number. ## ## * For a positive number, returns the same number. ## * For a negative number, returns the same number except positive. @@ -670,7 +670,7 @@ isFinite : Frac * -> Bool ## Calling this on an unsigned integer (like [U32] or [U64]) never does anything. abs : Num a -> Num a -## Return the absolute difference between two numbers. +## Returns the absolute difference between two numbers. ## ## ``` ## Num.absDiff 5 3 @@ -691,7 +691,7 @@ absDiff = \a, b -> else b - a -## Return a negative number when given a positive one, and vice versa. +## Returns a negative number when given a positive one, and vice versa. ## ``` ## Num.neg 5 ## @@ -712,7 +712,7 @@ absDiff = \a, b -> ## (It will never crash when given a [Frac], however, because of how floating point numbers represent positive and negative numbers.) neg : Num a -> Num a -## Add two numbers of the same type. +## Adds two numbers of the same type. ## ## (To add an [Int] and a [Frac], first convert one so that they both have the same type. There are functions in this module that can convert both [Int] to [Frac] and the other way around.) ## @@ -733,7 +733,7 @@ neg : Num a -> Num a ## ∞ or -∞. For all other number types, overflow results in a panic. add : Num a, Num a -> Num a -## Subtract two numbers of the same type. +## Subtracts two numbers of the same type. ## ## (To subtract an [Int] and a [Frac], first convert one so that they both have the same type. There are functions in this module that can convert both [Int] to [Frac] and the other way around.) ## @@ -754,7 +754,7 @@ add : Num a, Num a -> Num a ## ∞ or -∞. For all other number types, overflow results in a panic. sub : Num a, Num a -> Num a -## Multiply two numbers of the same type. +## Multiplies two numbers of the same type. ## ## (To multiply an [Int] and a [Frac], first convert one so that they both have the same type. There are functions in this module that can convert both [Int] to [Frac] and the other way around.) ## @@ -833,7 +833,7 @@ logChecked = \x -> else Ok (Num.log x) -## Divide one [Frac] by another. +## Divides one [Frac] by another. ## ## `a / b` is shorthand for `Num.div a b`. ## @@ -882,12 +882,12 @@ divCeilChecked = \a, b -> else Ok (Num.divCeil a b) -## Divide two integers, truncating the result towards zero. +## Divides two integers, truncating the result towards zero. ## ## `a // b` is shorthand for `Num.divTrunc a b`. ## ## Division by zero is undefined in mathematics. As such, you should make -## sure never to pass zero as the denomaintor to this function! If you do, +## sure never to pass zero as the denominator to this function! If you do, ## it will crash. ## ``` ## 5 // 7 @@ -907,7 +907,7 @@ divTruncChecked = \a, b -> else Ok (Num.divTrunc a b) -## Obtain the remainder (truncating modulo) from the division of two integers. +## Obtains the remainder (truncating modulo) from the division of two integers. ## ## `a % b` is shorthand for `Num.rem a b`. ## ``` @@ -1046,7 +1046,7 @@ countOneBits : Int a -> Nat addWrap : Int range, Int range -> Int range -## Add two numbers, clamping on the maximum representable number rather than +## Adds two numbers, clamping on the maximum representable number rather than ## overflowing. ## ## This is the same as [Num.add] except for the saturating behavior if the @@ -1055,7 +1055,7 @@ addWrap : Int range, Int range -> Int range ## yield 255, the maximum value of a `U8`. addSaturated : Num a, Num a -> Num a -## Add two numbers and check for overflow. +## Adds two numbers and checks for overflow. ## ## This is the same as [Num.add] except if the operation overflows, instead of ## panicking or returning ∞ or -∞, it will return `Err Overflow`. @@ -1072,7 +1072,7 @@ addCheckedLowlevel : Num a, Num a -> { b : Bool, a : Num a } subWrap : Int range, Int range -> Int range -## Subtract two numbers, clamping on the minimum representable number rather +## Subtracts two numbers, clamping on the minimum representable number rather ## than overflowing. ## ## This is the same as [Num.sub] except for the saturating behavior if the @@ -1081,7 +1081,7 @@ subWrap : Int range, Int range -> Int range ## yield 0, the minimum value of a `U8`. subSaturated : Num a, Num a -> Num a -## Subtract two numbers and check for overflow. +## Subtracts two numbers and checks for overflow. ## ## This is the same as [Num.sub] except if the operation overflows, instead of ## panicking or returning ∞ or -∞, it will return `Err Overflow`. @@ -1098,14 +1098,14 @@ subCheckedLowlevel : Num a, Num a -> { b : Bool, a : Num a } mulWrap : Int range, Int range -> Int range -## Multiply two numbers, clamping on the maximum representable number rather than +## Multiplies two numbers, clamping on the maximum representable number rather than ## overflowing. ## ## This is the same as [Num.mul] except for the saturating behavior if the ## addition is to overflow. mulSaturated : Num a, Num a -> Num a -## Multiply two numbers and check for overflow. +## Multiplies two numbers and checks for overflow. ## ## This is the same as [Num.mul] except if the operation overflows, instead of ## panicking or returning ∞ or -∞, it will return `Err Overflow`. @@ -1120,8 +1120,8 @@ mulChecked = \a, b -> mulCheckedLowlevel : Num a, Num a -> { b : Bool, a : Num a } -## The lowest number that can be stored in an [I8] without underflowing its -## available memory and crashing. +## Returns the lowest number that can be stored in an [I8] without underflowing +## its available memory and crashing. ## ## For reference, this number is `-128`. ## @@ -1130,8 +1130,8 @@ mulCheckedLowlevel : Num a, Num a -> { b : Bool, a : Num a } minI8 : I8 minI8 = -128i8 -## The highest number that can be stored in an [I8] without overflowing its -## available memory and crashing. +## Returns the highest number that can be stored in an [I8] without overflowing +## its available memory and crashing. ## ## For reference, this number is `127`. ## @@ -1140,8 +1140,8 @@ minI8 = -128i8 maxI8 : I8 maxI8 = 127i8 -## The lowest number that can be stored in a [U8] without underflowing its -## available memory and crashing. +## Returns the lowest number that can be stored in a [U8] without underflowing +## its available memory and crashing. ## ## For reference, this number is zero, because [U8] is ## [unsigned](https://en.wikipedia.org/wiki/Signed_number_representations), @@ -1150,15 +1150,15 @@ maxI8 = 127i8 minU8 : U8 minU8 = 0u8 -## The highest number that can be stored in a [U8] without overflowing its -## available memory and crashing. +## Returns the highest number that can be stored in a [U8] without overflowing +## its available memory and crashing. ## ## For reference, this number is `255`. maxU8 : U8 maxU8 = 255u8 -## The lowest number that can be stored in an [I16] without underflowing its -## available memory and crashing. +## Returns the lowest number that can be stored in an [I16] without underflowing +## its available memory and crashing. ## ## For reference, this number is `-32_768`. ## @@ -1167,8 +1167,8 @@ maxU8 = 255u8 minI16 : I16 minI16 = -32768i16 -## The highest number that can be stored in an [I16] without overflowing its -## available memory and crashing. +## Returns the highest number that can be stored in an [I16] without overflowing +## its available memory and crashing. ## ## For reference, this number is `32_767`. ## @@ -1177,8 +1177,8 @@ minI16 = -32768i16 maxI16 : I16 maxI16 = 32767i16 -## The lowest number that can be stored in a [U16] without underflowing its -## available memory and crashing. +## Returns the lowest number that can be stored in a [U16] without underflowing +## its available memory and crashing. ## ## For reference, this number is zero, because [U16] is ## [unsigned](https://en.wikipedia.org/wiki/Signed_number_representations), @@ -1187,15 +1187,15 @@ maxI16 = 32767i16 minU16 : U16 minU16 = 0u16 -## The highest number that can be stored in a [U16] without overflowing its -## available memory and crashing. +## Returns the highest number that can be stored in a [U16] without overflowing +## its available memory and crashing. ## ## For reference, this number is `65_535`. maxU16 : U16 maxU16 = 65535u16 -## The lowest number that can be stored in an [I32] without underflowing its -## available memory and crashing. +## Returns the lowest number that can be stored in an [I32] without underflowing +## its available memory and crashing. ## ## For reference, this number is `-2_147_483_648`. ## @@ -1204,8 +1204,8 @@ maxU16 = 65535u16 minI32 : I32 minI32 = -2147483648 -## The highest number that can be stored in an [I32] without overflowing its -## available memory and crashing. +## Returns the highest number that can be stored in an [I32] without overflowing +## its available memory and crashing. ## ## For reference, this number is `2_147_483_647`, ## which is over 2 million. @@ -1215,8 +1215,8 @@ minI32 = -2147483648 maxI32 : I32 maxI32 = 2147483647 -## The lowest number that can be stored in a [U32] without underflowing its -## available memory and crashing. +## Returns the lowest number that can be stored in a [U32] without underflowing +## its available memory and crashing. ## ## For reference, this number is zero, because [U32] is ## [unsigned](https://en.wikipedia.org/wiki/Signed_number_representations), @@ -1225,15 +1225,15 @@ maxI32 = 2147483647 minU32 : U32 minU32 = 0 -## The highest number that can be stored in a [U32] without overflowing its -## available memory and crashing. +## Returns the highest number that can be stored in a [U32] without overflowing +## its available memory and crashing. ## ## For reference, this number is `4_294_967_295`. maxU32 : U32 maxU32 = 4294967295 -## The lowest number that can be stored in an [I64] without underflowing its -## available memory and crashing. +## Returns the lowest number that can be stored in an [I64] without underflowing +## its available memory and crashing. ## ## For reference, this number is `-9_223_372_036_854_775_808`, ## which is under 9 quintillion. @@ -1243,8 +1243,8 @@ maxU32 = 4294967295 minI64 : I64 minI64 = -9223372036854775808 -## The highest number that can be stored in an [I64] without overflowing its -## available memory and crashing. +## Returns the highest number that can be stored in an [I64] without overflowing +## its available memory and crashing. ## ## For reference, this number is `9_223_372_036_854_775_807`, ## which is over 9 quintillion. @@ -1254,8 +1254,8 @@ minI64 = -9223372036854775808 maxI64 : I64 maxI64 = 9223372036854775807 -## The lowest number that can be stored in a [U64] without underflowing its -## available memory and crashing. +## Returns the lowest number that can be stored in a [U64] without underflowing +## its available memory and crashing. ## ## For reference, this number is zero, because [U64] is ## [unsigned](https://en.wikipedia.org/wiki/Signed_number_representations), @@ -1264,16 +1264,16 @@ maxI64 = 9223372036854775807 minU64 : U64 minU64 = 0 -## The highest number that can be stored in a [U64] without overflowing its -## available memory and crashing. +## Returns the highest number that can be stored in a [U64] without overflowing +## its available memory and crashing. ## ## For reference, this number is `18_446_744_073_709_551_615`, ## which is over 18 quintillion. maxU64 : U64 maxU64 = 18446744073709551615 -## The lowest number that can be stored in an [I128] without underflowing its -## available memory and crashing. +## Returns the lowest number that can be stored in an [I128] without underflowing +## its available memory and crashing. ## ## For reference, this number is `-170_141_183_460_469_231_731_687_303_715_884_105_728`. ## which is under 170 undecillion. @@ -1283,8 +1283,8 @@ maxU64 = 18446744073709551615 minI128 : I128 minI128 = -170141183460469231731687303715884105728 -## The highest number that can be stored in an [I128] without overflowing its -## available memory and crashing. +## Returns the highest number that can be stored in an [I128] without overflowing +## its available memory and crashing. ## ## For reference, this number is `170_141_183_460_469_231_731_687_303_715_884_105_727`, ## which is over 170 undecillion. @@ -1294,8 +1294,8 @@ minI128 = -170141183460469231731687303715884105728 maxI128 : I128 maxI128 = 170141183460469231731687303715884105727 -## The lowest number that can be stored in a [U128] without underflowing its -## available memory and crashing. +## Returns the lowest number that can be stored in a [U128] without underflowing +## its available memory and crashing. ## ## For reference, this number is zero, because [U128] is ## [unsigned](https://en.wikipedia.org/wiki/Signed_number_representations), @@ -1304,8 +1304,8 @@ maxI128 = 170141183460469231731687303715884105727 minU128 : U128 minU128 = 0 -## The highest number that can be stored in a [U128] without overflowing its -## available memory and crashing. +## Returns the highest number that can be stored in a [U128] without overflowing +## its available memory and crashing. ## ## For reference, this number is `340_282_366_920_938_463_463_374_607_431_768_211_455`, ## which is over 340 undecillion. @@ -1337,7 +1337,7 @@ toU32 : Int * -> U32 toU64 : Int * -> U64 toU128 : Int * -> U128 -## Convert an [Int] to a [Nat]. If the given number doesn't fit in [Nat], it will be truncated. +## Converts an [Int] to a [Nat]. If the given number doesn't fit in [Nat], it will be truncated. ## Since [Nat] has a different maximum number depending on the system you're building ## for, this may give a different answer on different systems. ## diff --git a/crates/compiler/builtins/roc/Result.roc b/crates/compiler/builtins/roc/Result.roc index 596a3e78da..a9075aebbf 100644 --- a/crates/compiler/builtins/roc/Result.roc +++ b/crates/compiler/builtins/roc/Result.roc @@ -6,7 +6,7 @@ interface Result ## okay, or else there was an error of some sort. Result ok err : [Ok ok, Err err] -## Return `Bool.true` if the result indicates a success, else return `Bool.false` +## Returns `Bool.true` if the result indicates a success, else returns `Bool.false` ## ``` ## Result.isOk (Ok 5) ## ``` @@ -16,7 +16,7 @@ isOk = \result -> Ok _ -> Bool.true Err _ -> Bool.false -## Return `Bool.true` if the result indicates a failure, else return `Bool.false` +## Returns `Bool.true` if the result indicates a failure, else returns `Bool.false` ## ``` ## Result.isErr (Err "uh oh") ## ``` @@ -26,7 +26,7 @@ isErr = \result -> Ok _ -> Bool.false Err _ -> Bool.true -## If the result is `Ok`, return the value it holds. Otherwise, return +## If the result is `Ok`, returns the value it holds. Otherwise, returns ## the given default value. ## ``` ## Result.withDefault (Ok 7) 42 @@ -38,8 +38,8 @@ withDefault = \result, default -> Ok value -> value Err _ -> default -## If the result is `Ok`, transform the value it holds by running a conversion -## function on it. Then return a new `Ok` holding the transformed value. If the +## If the result is `Ok`, transforms the value it holds by running a conversion +## function on it. Then returns a new `Ok` holding the transformed value. If the ## result is `Err`, this has no effect. Use [mapErr] to transform an `Err`. ## ``` ## Result.map (Ok 12) Num.negate @@ -54,8 +54,8 @@ map = \result, transform -> Ok v -> Ok (transform v) Err e -> Err e -## If the result is `Err`, transform the value it holds by running a conversion -## function on it. Then return a new `Err` holding the transformed value. If +## If the result is `Err`, transforms the value it holds by running a conversion +## function on it. Then returns a new `Err` holding the transformed value. If ## the result is `Ok`, this has no effect. Use [map] to transform an `Ok`. ## ``` ## Result.mapErr (Err "yipes!") Str.isEmpty @@ -67,8 +67,8 @@ mapErr = \result, transform -> Ok v -> Ok v Err e -> Err (transform e) -## If the result is `Ok`, transform the entire result by running a conversion -## function on the value the `Ok` holds. Then return that new result. If the +## If the result is `Ok`, transforms the entire result by running a conversion +## function on the value the `Ok` holds. Then returns that new result. If the ## result is `Err`, this has no effect. Use `onErr` to transform an `Err`. ## ``` ## Result.try (Ok -1) \num -> if num < 0 then Err "negative!" else Ok -num @@ -80,8 +80,8 @@ try = \result, transform -> Ok v -> transform v Err e -> Err e -## If the result is `Err`, transform the entire result by running a conversion -## function on the value the `Err` holds. Then return that new result. If the +## If the result is `Err`, transforms the entire result by running a conversion +## function on the value the `Err` holds. Then returns that new result. If the ## result is `Ok`, this has no effect. Use `try` to transform an `Ok`. ## ``` ## Result.onErr (Ok 10) \errorNum -> Str.toNat errorNum