format Option docstrings (#42)

Author: aspeddro

src/Core__Option.resi

@@ -22,224 +22,233 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
 
-/**
-   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, we provide utility-functions for it.
+/***
+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, we provide utility-functions for it.
 
-   The `option` type is a part of the ReScript standard library which is defined
-   like this:
+The `option` type is a part of the ReScript standard library which is defined
+like this:
 
-   ```res sig
-   type option<'a> = None | Some('a)
-   ```
+```rescript
+type option<'a> = None | Some('a)
+```
 
-   ```res example
-   let someString: option<string> = Some("hello")
-   ```
+```rescript
+let someString: option<string> = Some("hello")
+```
 */
+
 /**
-   If `optionValue` is `Some(value)` and `p(value) = true`, it returns `Some(value)`; otherwise returns `None`
+`filter(opt, f)` applies `f` to `opt`, if `f` returns `true`, then it returns `Some(value)`, otherwise returns `None`.
+
+## Examples
 
-   ```res example
-   Option.filter(Some(10), x => x > 5) /* returns `Some(10)` */
-   Option.filter(Some(4), x => x > 5) /* returns `None` */
-   Option.filter(None, x => x > 5) /* returns `None` */
-   ```
+```rescript
+Option.filter(Some(10), x => x > 5) // Some(10)
+Option.filter(Some(4), x => x > 5) // None
+Option.filter(None, x => x > 5) // None
+```
 */
 let filter: (option<'a>, 'a => bool) => option<'a>
 
 /**
-   If `optionValue` is `Some(value`), it calls `f(value)`; otherwise returns `()`
+`forEach(opt, f)` call `f` on `opt`. if `opt` is `Some(value)`, then if calls
+`f`, otherwise returns `unit`.
 
-   ```res example
-   Option.forEach(Some("thing"), x => Console.log(x)) /* logs "thing" */
-   Option.forEach(None, x => Console.log(x)) /* returns () */
-   ```
+## Examples
+
+```rescript
+Option.forEach(Some("thing"), x => Console.log(x)) // logs "thing"
+Option.forEach(None, x => Console.log(x)) // returns ()
+```
 */
 let forEach: (option<'a>, 'a => unit) => unit
 
 /**
-   Raises an Error in case `None` is provided. Use with care.
+`getExn(opt)` raises an Error in case `None` is provided.
+
+```rescript
+Option.getExn(Some(3)) // 3
+Option.getExn(None) /* Raises an Error */
+```
 
-   ```res example
-   Option.getExn(Some(3)) /* 3 */
+## Exceptions
 
-   Option.getExn(None) /* Raises an Error */
-   ```
+- Raises an error if `opt` is `None`
 */
 let getExn: option<'a> => 'a
 
 /**
-   `getUnsafe(x)` returns `x`
+`getUnsafe(value)` returns `value`.
+
+## Examples
 
-   This is an unsafe operation, it assumes `x` is neither `None`
-   nor `Some(None(...)))`
+```rescript
+Option.getUnsafe(Some(3)) == 3
+Option.getUnsafe(None) // Raises an error
+```
+
+## Exceptions
+
+- This is an unsafe operation, it assumes `value` is neither `None` nor `Some(None(...)))`
 */
 external getUnsafe: option<'a> => 'a = "%identity"
 
 /**
-   If `optionValue` is of `Some(value)`,
-   this function returns that value applied with `f`, in other words `f(value)`.
+`mapWithDefault(opt, default, f)` applies `f` to `opt`, if `opt` is `None`, then
+`f` return `default`, otherwise return that value applied with `f`.
 
-   If `optionValue` is `None`, the default is returned.
+## Examples
 
-   ```res example
-   let someValue = Some(3)
-   someValue->Option.mapWithDefault(0, x => x + 5) /* 8 */
+```rescript
+let someValue = Some(3)
+someValue->Option.mapWithDefault(0, x => x + 5) // 8
 
-   let noneValue = None
-   noneValue->Option.mapWithDefault(0, x => x + 5) /* 0 */
-   ```
+let noneValue = None
+noneValue->Option.mapWithDefault(0, x => x + 5) // 0
+```
 */
 let mapWithDefault: (option<'a>, 'b, 'a => 'b) => 'b
 
 /**
-   If `optionValue` is `Some(value)` this returns `f(value)`, otherwise it returns `None`.
+`map(opt f)` applies `f` to `opt`, if `opt` is `Some(value)` this returns
+`f(value)`, otherwise it returns `None`.
 
-   ```res example
-   Option.map(Some(3), x => x * x) /* Some(9) */
+## Examples
 
-   Option.map(None, x => x * x) /* None */
-   ```
+```rescript
+Option.map(Some(3), x => x * x) // Some(9)
+Option.map(None, x => x * x) // None
+```
 */
 let map: (option<'a>, 'a => 'b) => option<'b>
 
 /**
-   If `optionValue` is `Some(value)`, returns `f(value)`, otherwise returns
-   `None`.<br/>
-   The function `f` must have a return type of `option<'b>`.
-
-   ```res example
-   let addIfAboveOne = value =>
-     if (value > 1) {
-       Some(value + 1)
-     } else {
-       None
-     }
-
-   Option.flatMap(Some(2), addIfAboveOne) /* Some(3) */
-
-   Option.flatMap(Some(-4), addIfAboveOne) /* None */
-
-   Option.flatMap(None, addIfAboveOne) /* None */
-   ```
+`flatMap(opt, f)` returns `f` applied to `opt` if `opt` is `Some(value)`,
+otherwise `None`. The function `f` must have a return type of `option<'b>`.
+
+## Examples
+
+```rescript
+let addIfAboveOne = value =>
+  if (value > 1) {
+    Some(value + 1)
+  } else {
+    None
+  }
+
+Option.flatMap(Some(2), addIfAboveOne) // Some(3)
+Option.flatMap(Some(-4), addIfAboveOne) // None
+Option.flatMap(None, addIfAboveOne) // None
+```
 */
 let flatMap: (option<'a>, 'a => option<'b>) => option<'b>
 
 /**
-   If `optionalValue` is `Some(value)`, returns `value`, otherwise default.
-
-   ```res example
-   Option.getWithDefault(None, "Banana") /* Banana */
+`getWithDefault(opt, default)` returns `value` if `opt` is `Some(value)`,
+otherwise return `default` if `opt` is `None`.
 
-   Option.getWithDefault(Some("Apple"), "Banana") /* Apple */
-   ```
+## Examples
 
-   ```res example
-   let greet = (firstName: option<string>) =>
-     "Greetings " ++ firstName->Option.getWithDefault("Anonymous")
+```rescript
+Option.getWithDefault(None, "Banana") // Banana
+Option.getWithDefault(Some("Apple"), "Banana") // Apple
 
-   Some("Jane")->greet /* "Greetings Jane" */
+let greet = (firstName: option<string>) =>
+  "Greetings " ++ firstName->Option.getWithDefault("Anonymous")
 
-   None->greet /* "Greetings Anonymous" */
-   ```
+Some("Jane")->greet // "Greetings Jane"
+None->greet // "Greetings Anonymous"
+```
 */
 let getWithDefault: (option<'a>, 'a) => 'a
 
 /**
-   `orElse optionalValue otherOptional`
+`orElse(opt1, opt2)` returns `opt2` if `opt1` is `None`, otherwise `opt1`.
 
-   If `optionalValue` is `Some value`, returns `Some value`, otherwise `otherOptional`
+## Examples
 
-   ```
-   orElse (Some 1812) (Some 1066) = Some 1812;;
-   orElse None (Some 1066) = Some 1066;;
-   orElse None None = None;;
-   ```
+```rescript
+Option.orElse(Some(1812), Some(1066)) == Some(1812)
+Option.orElse(None, Some(1066) == Some(1066)
+Option.orElse(None, None) == None
+```
 */
 let orElse: (option<'a>, option<'a>) => option<'a>
 
 /**
-   Returns `true` if the argument is `Some(value)`, `false` otherwise.
+`isSome(opt)` returns `true` if `opt` is `Some(value)`, otherwise returns `false`.
 
-   ```res example
-   Option.isSome(None) /* false */
+## Examples
 
-   Option.isSome(Some(1)) /* true */
-   ```
+```rescript
+Option.isSome(None) // false
+Option.isSome(Some(1)) // true
+```
 */
 let isSome: option<'a> => bool
 
 /**
-   Returns `true` if the argument is `None`, `false` otherwise.
+`isNone(opt)` returns `true` if `opt` is `None`, false otherwise.
 
-   ```res example
-   Option.isNone(None) /* true */
+## Examples
 
-   Option.isNone(Some(1)) /* false */
-   ```
+```rescript
+Option.isNone(None) // true
+Option.isNone(Some(1)) // false
+```
 */
 let isNone: option<'a> => bool
 
 /**
-   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`.
-
-   If arguments are `Some(value1)` and `Some(value2)`, returns the result of
-   `predicate(value1, value2)`; the predicate function must return a bool.
-
-   ```res example
-   let clockEqual = (a, b) => mod(a, 12) == mod(b, 12)
-
-   open Option
+`eq(opt1, opt2, f)` evaluates two optional values for equality with respect to a predicate function `f`. If both `opt1` and `opt2` are `None`, returns `true`.
+If one of the arguments is `Some(value)` and the other is `None`, returns
+`false`.
+If arguments are `Some(value1)` and `Some(value2)`, returns the result of
+`f(value1, value2)`, the predicate function `f` must return a bool.
 
-   eq(Some(3), Some(15), clockEqual) /* true */
+## Examples
 
-   eq(Some(3), None, clockEqual) /* false */
+```rescript
+let clockEqual = (a, b) => mod(a, 12) == mod(b, 12)
 
-   eq(None, Some(3), clockEqual) /* false */
+open Option
 
-   eq(None, None, clockEqual) /* true */
-   ```
+eq(Some(3), Some(15), clockEqual) // true
+eq(Some(3), None, clockEqual) // false
+eq(None, Some(3), clockEqual) // false
+eq(None, None, clockEqual) // true
+```
 */
 let eq: (option<'a>, option<'b>, ('a, 'b) => bool) => bool
 
 /**
-   `cmp(optValue1, optValue2, comparisonFunction)` compares two optional values
-   with respect to given `comparisonFunction`.
-
-   If both `optValue1` and `optValue2` are `None`, it 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 `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.
-
-   ```res example
-   let clockCompare = (a, b) => compare(mod(a, 12), mod(b, 12))
+`cmp(opt1, opt2, f)` compares two optional values with respect to given `f`.
 
-   open Option
+If both `opt1` and `opt2` are `None`, it returns `0`. If the first argument is `Some(value1)` and the second is `None`, returns `1` (something is greater than nothing).
 
-   cmp(Some(3), Some(15), clockCompare) /* 0 */
+If the first argument is `None` and the second is `Some(value2)`, returns `-1`
+(nothing is less than something).
 
-   cmp(Some(3), Some(14), clockCompare) /* 1 */
+If the arguments are `Some(value1)` and `Some(value2)`, returns the result of
+`f(value1, value2)`, `f` 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.
 
-   cmp(Some(2), Some(15), clockCompare) /* (-1) */
+## Examples
 
-   cmp(None, Some(15), clockCompare) /* (-1) */
+```rescript
+let clockCompare = (a, b) => compare(mod(a, 12), mod(b, 12))
 
-   cmp(Some(14), None, clockCompare) /* 1 */
+open Option
 
-   cmp(None, None, clockCompare) /* 0 */
-   ```
+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
+```
 */
 let cmp: (option<'a>, option<'b>, ('a, 'b) => int) => int