Merge pull request #5424 from nkrkv/sync-belt-doc-headers-option

Sync belt doc headers for `Option`

Author: ryyppy

jscomp/others/belt_Option.mli

@@ -22,9 +22,20 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *)
 
-(** [`Belt.Option`]()
+(**
+   In Belt we represent the existence and nonexistence of a value by wrapping it
+   with the `option` type.  In order to make it a bit more convenient to work with
+   option-types, Belt provides utility-functions for it.
+
+   The `option` type is a part of the ReScript standard library which is defined like this:
 
-    Utilities for option data type
+   ```res sig
+   type option<'a> = None | Some('a)
+   ```
+
+   ```res example
+   let someString: option<string> = Some("hello")
+   ```
 *)
 
 
@@ -33,14 +44,12 @@ val keepU : 'a option -> ('a -> bool [@bs]) -> 'a option
 
 val keep : 'a option -> ('a -> bool) -> 'a option
 (**
-   `keep optionValue p`
+   If `optionValue` is `Some(value)` and `p(value) = true`, it returns `Some(value)`; otherwise returns `None`
 
-   If `optionValue` is `Some value` and `p value = true`, it returns `Some value`; otherwise returns `None`
-
-   ```
-   keep (Some 10)(fun x -> x > 5);; (* returns `Some 10` *)
-   keep (Some 4)(fun x -> x > 5);; (* returns `None` *)
-   keep None (fun x -> x > 5);; (* returns `None` *)
+   ```res example
+   Belt.Option.keep(Some(10), x => x > 5) /* returns `Some(10)` */
+   Belt.Option.keep(Some(4), x => x > 5) /* returns `None` */
+   Belt.Option.keep(None, x => x > 5) /* returns `None` */
    ```
 *)
 
@@ -49,45 +58,50 @@ val forEachU : 'a option -> ('a -> unit [@bs]) -> unit
 
 val forEach : 'a option -> ('a -> unit) -> unit
 (**
-   `forEach optionValue f`
-
-   If `optionValue` is `Some value`, it calls `f value`; otherwise returns `()`
+   If `optionValue` is `Some(value`), it calls `f(value)`; otherwise returns `()`
 
-   ```
-   forEach (Some "thing")(fun x -> Js.log x);; (* logs "thing" *)
-   forEach None (fun x -> Js.log x);; (* returns () *)
+   ```res example
+   Belt.Option.forEach(Some("thing"), x => Js.log(x)) /* logs "thing" */
+   Belt.Option.forEach(None, x => Js.log(x)) /* returns () */
    ```
 *)
 
 val getExn : 'a option -> 'a
-(** `getExn optionalValue`
-    Returns `value` if `optionalValue` is `Some value`, otherwise raises `getExn`
+(**
+   Raises an Error in case `None` is provided. Use with care.
 
-    ```
-    getExn (Some 3) = 3;;
-    getExn None (* Raises getExn error *)
-    ```
+   ```res example
+   Belt.Option.getExn(Some(3)) /* 3 */
+
+   Belt.Option.getExn(None) /* Raises an Error */
+   ```
 *)
 
 external getUnsafe :
   'a option -> 'a = "%identity"
-(** `getUnsafe x` returns x
-    This is an unsafe operation, it assumes x is neither not None
-    or (Some (None .. ))
+(**
+   `getUnsafe(x)` returns `x`
+
+   This is an unsafe operation, it assumes `x` is neither `None`
+   nor `Some(None(...)))`
 *)
 
 val mapWithDefaultU : 'a option -> 'b -> ('a -> 'b [@bs]) -> 'b
 (** Uncurried version of `mapWithDefault` *)
 
 val mapWithDefault : 'a option -> 'b -> ('a -> 'b) -> 'b
 (**
-   `mapWithDefault optionValue default f`
+   If `optionValue` is of `Some(value)`,
+   this function returns that value applied with `f`, in other words `f(value)`.
 
-   If `optionValue` is `Some value`, returns `f value`; otherwise returns `default`
+   If `optionValue` is `None`, the default is returned.
 
-   ```
-   mapWithDefault (Some 3) 0 (fun x -> x + 5) = 8;;
-   mapWithDefault None 0 (fun x -> x + 5) = 0;;
+   ```res example
+   let someValue = Some(3)
+   someValue->Belt.Option.mapWithDefault(0, x => x + 5) /* 8 */
+
+   let noneValue = None
+   noneValue->Belt.Option.mapWithDefault(0, x => x + 5) /* 0 */
    ```
 *)
 
@@ -96,13 +110,12 @@ val mapU : 'a option -> ('a -> 'b [@bs]) -> 'b option
 
 val map : 'a option -> ('a -> 'b) -> 'b option
 (**
-   `map optionValue f`
+   If `optionValue` is `Some(value)` this returns `f(value)`, otherwise it returns `None`.
 
-   If `optionValue` is `Some value`, returns `Some (f value)`; otherwise returns `None`
+   ```res example
+   Belt.Option.map(Some(3), x => x * x) /* Some(9) */
 
-   ```
-   map (Some 3) (fun x -> x * x) = (Some 9);;
-   map None (fun x -> x * x) = None;;
+   Belt.Option.map(None, x => x * x) /* None */
    ```
 *)
 
@@ -111,44 +124,66 @@ val flatMapU : 'a option -> ('a -> 'b option [@bs]) -> 'b option
 
 val flatMap : 'a option -> ('a -> 'b option) -> 'b option
 (**
-   `flatMap optionValue f`
+   If `optionValue` is `Some(value)`, returns `f(value)`, otherwise returns
+   `None`.<br/>
+   The function `f` must have a return type of `option<'b>`.
 
-   If `optionValue` is `Some value`, returns `f value`; otherwise returns `None`
-   The function `f` must have a return type of `'a option`
+   ```res example
+   let addIfAboveOne = value =>
+     if (value > 1) {
+       Some(value + 1)
+     } else {
+       None
+     }
 
-   ```
-   let f (x : float) =
-     if x >= 0.0 then
-       Some (sqrt x)
-     else
-       None;;
-
-   flatMap (Some 4.0) f = Some 2.0;;
-   flatMap (Some (-4.0)) f = None;;
-   flatMap None f = None;;
+   Belt.Option.flatMap(Some(2), addIfAboveOne) /* Some(3) */
+
+   Belt.Option.flatMap(Some(-4), addIfAboveOne) /* None */
+
+   Belt.Option.flatMap(None, addIfAboveOne) /* None */
    ```
 *)
 
 val getWithDefault : 'a option -> 'a -> 'a
 (**
-   `getWithDefault optionalValue default`
+   If `optionalValue` is `Some(value)`, returns `value`, otherwise default.
 
-   If `optionalValue` is `Some value`, returns `value`, otherwise `default`
+   ```res example
+   Belt.Option.getWithDefault(None, "Banana") /* Banana */
 
+   Belt.Option.getWithDefault(Some("Apple"), "Banana") /* Apple */
    ```
-   getWithDefault (Some 1812) 1066 = 1812;;
-   getWithDefault None 1066 = 1066;;
+
+   ```res example
+   let greet = (firstName: option<string>) =>
+     "Greetings " ++ firstName->Belt.Option.getWithDefault("Anonymous")
+
+   Some("Jane")->greet /* "Greetings Jane" */
+
+   None->greet /* "Greetings Anonymous" */
    ```
 *)
 
 val isSome : 'a option -> bool
 (**
-   Returns `true` if the argument is `Some value`, `false` otherwise
+   Returns `true` if the argument is `Some(value)`, `false` otherwise.
+
+   ```res example
+   Belt.Option.isSome(None) /* false */
+
+   Belt.Option.isSome(Some(1)) /* true */
+   ```
 *)
 
 val isNone : 'a option -> bool
 (**
-   Returns `true` if the argument is `None`, `false` otherwise
+   Returns `true` if the argument is `None`, `false` otherwise.
+
+   ```res example
+   Belt.Option.isNone(None) /* true */
+
+   Belt.Option.isNone(Some(1)) /* false */
+   ```
 *)
 
 val eqU : 'a option -> 'b option -> ('a -> 'b -> bool [@bs]) -> bool
@@ -158,23 +193,26 @@ val eqU : 'a option -> 'b option -> ('a -> 'b -> bool [@bs]) -> bool
 
 val eq : 'a option -> 'b option -> ('a -> 'b -> bool) -> bool
 (**
-   `eq optValue1 optvalue2 predicate`
+   Evaluates two optional values for equality with respect to a predicate
+   function. If both `optValue1` and `optValue2` are `None`, returns `true`.
+   If one of the arguments is `Some(value)` and the other is `None`, returns
+   `false`.
 
-   Evaluates two optional values for equality with respect to a predicate function.
+   If arguments are `Some(value1)` and `Some(value2)`, returns the result of
+   `predicate(value1, value2)`; the predicate function must return a bool.
 
-   If both `optValue1` and `optValue2` are `None`, returns `true`.
+   ```res example
+   let clockEqual = (a, b) => mod(a, 12) == mod(b, 12)
 
-   If one of the arguments is `Some value` and the other is `None`, returns `false`
+   open Belt.Option
 
-   If arguments are `Some value1` and `Some value2`, returns the result of `predicate value1 value2`;
-   the `predicate` function must return a `bool`
+   eq(Some(3), Some(15), clockEqual) /* true */
 
-   ```
-   let clockEqual = (fun a b -> a mod 12 = b mod 12);;
-   eq (Some 3) (Some 15) clockEqual = true;;
-   eq (Some 3) None clockEqual = false;;
-   eq None (Some 3) clockEqual = false;;
-   eq None None clockEqual = true;;
+   eq(Some(3), None, clockEqual) /* false */
+
+   eq(None, Some(3), clockEqual) /* false */
+
+   eq(None, None, clockEqual) /* true */
    ```
 *)
 
@@ -183,25 +221,37 @@ val cmpU : 'a option -> 'b option -> ('a -> 'b -> int [@bs]) -> int
 
 val cmp : 'a option -> 'b option -> ('a -> 'b -> int) -> int
 (**
-   `cmp optValue1 optvalue2 comparisonFcn`
+   `cmp(optValue1, optValue2, comparisonFunction)` compares two optional values
+   with respect to given `comparisonFunction`.
 
-   Compares two optional values with respect to a comparison function
+   If both `optValue1` and `optValue2` are `None`, it returns `0`.
 
-   If both `optValue1` and `optValue2` are `None`, returns 0.
+   If the first argument is `Some(value1)` and the second is `None`, returns `1`
+   (something is greater than nothing).
 
-   If the first argument is `Some value1` and the second is `None`, returns 1 (something is greater than nothing)
+   If the first argument is `None` and the second is `Some(value2)`, returns `-1`
+   (nothing is less than something).
 
-   If the first argument is `None` and the second is `Some value2`, returns -1 (nothing is less than something)
+   If the arguments are `Some(value1)` and `Some(value2)`, returns the result of
+   `comparisonFunction(value1, value2)`; comparisonFunction takes two arguments
+   and returns `-1` if the first argument is less than the second, `0` if the
+   arguments are equal, and `1` if the first argument is greater than the second.
 
-   If the arguments are `Some value1` and `Some value2`, returns the result of `comparisonFcn value1 value2`; `comparisonFcn` takes two arguments and returns -1 if the first argument is less than the second, 0 if the arguments are equal, and 1 if the first argument is greater than the second.
+   ```res example
+   let clockCompare = (a, b) => compare(mod(a, 12), mod(b, 12))
 
-   ```
-   let clockCompare = fun a b -> compare (a mod 12) (b mod 12);;
-   cmp (Some 3) (Some 15) clockCompare = 0;;
-   cmp (Some 3) (Some 14) clockCompare = 1;;
-   cmp (Some 2) (Some 15) clockCompare = -1;;
-   cmp None (Some 15) clockCompare = -1;;
-   cmp (Some 14) None clockCompare = 1;;
-   cmp None None clockCompare = 0;;
+   open Belt.Option
+
+   cmp(Some(3), Some(15), clockCompare) /* 0 */
+
+   cmp(Some(3), Some(14), clockCompare) /* 1 */
+
+   cmp(Some(2), Some(15), clockCompare) /* (-1) */
+
+   cmp(None, Some(15), clockCompare) /* (-1) */
+
+   cmp(Some(14), None, clockCompare) /* 1 */
+
+   cmp(None, None, clockCompare) /* 0 */
    ```
 *)