Markdown docstrings (Rescript 11)

Author: Lomand

src/Tablecloth.res

@@ -13,7 +13,7 @@ module Int = TableclothInt
 /** Functions for working with floating point numbers. */
 module Float = TableclothFloat
 
-/** Interfaces for use with container types like {!Array} or {!List} */
+/** Interfaces for use with container types like [Array](Array.mdx#) or [List](List.mdx#) */
 module Container = TableclothContainer
 
 /** A fixed lenfth collection of values */

src/TableclothArray.resi

@@ -3,13 +3,10 @@
   Has constant time (O(1)) [get](#get), [set](#set) and [length](#length) operations.
 
   Arrays have a fixed length, if you want to be able to add an arbitrary number of elements maybe you want a [List](List.mdx#)}.
+  You can create an `array` in Rescript with the `[1, 2, 3]` syntax.
 */
 type t<'a> = array<'a>
 
-/** # Create
-
-  You can create an `array` in Rescript with the `[1, 2, 3]` syntax.
-*/
 /** Create an array with only one element.
 
   ## Examples
@@ -92,7 +89,6 @@ let fromList: list<'a> => t<'a>
 */
 let clone: t<'a> => t<'a>
 
-/** # Basic operations */
 /** Get the element at the specified index.
 
   The first element has index number 0.
@@ -124,7 +120,7 @@ let get: (t<'a>, int) => 'a
 
 /** Returns, as an [Option](Option.mdx#), the element at index number `n` of array `a`.
 
-  Returns `None` if `n` is outside the range `0` to [(Array.length(a) - 1)].
+  Returns `None` if `n` is outside the range `0` to `Array.length(a) - 1`.
 
   ## Examples
 
@@ -251,7 +247,6 @@ let reverse: t<'a> => unit
 */
 let sort: (t<'a>, ~compare: ('a, 'a) => int) => unit
 
-/** # Query */
 /** Check if an array is empty.
 
   ## Examples
@@ -336,7 +331,7 @@ let find: (t<'a>, ~f: 'a => bool) => option<'a>
 */
 let findIndex: (t<'a>, ~f: (int, 'a) => bool) => option<(int, 'a)>
 
-/** Test if an array contains the specified element using the provided [equal] to test for equality.
+/** Test if an array contains the specified element using the provided `equal` to test for equality.
 
   ## Examples
 
@@ -408,7 +403,6 @@ let extent: (t<'a>, ~compare: ('a, 'a) => int) => option<('a, 'a)>
 */
 let sum: (t<'a>, module(TableclothContainer.Sum with type t = 'a)) => 'a
 
-/** # Transform */
 /** Create a new array which is the result of applying a function `f` to every element.
 
   ## Examples
@@ -560,7 +554,7 @@ let flatten: t<t<'a>> => t<'a>
 
   If one array is longer, the extra elements are dropped.
 
-  The same as [Array.map2(~f=Tuple2.make)]
+  The same as `Array.map2(~f=Tuple2.make)`
 
   ## Examples
 
@@ -605,7 +599,6 @@ let map2: (t<'a>, t<'b>, ~f: ('a, 'b) => 'c) => t<'c>
 */
 let map3: (t<'a>, t<'b>, t<'c>, ~f: ('a, 'b, 'c) => 'd) => t<'d>
 
-/** # Deconstruct */
 /** Split an array into a [Tuple2](Tuple2.mdx#) of arrays. Values which `f` returns true for will end up in [Tuple2.first](Tuple2.mdx#first).
 
   ## Examples
@@ -664,7 +657,6 @@ let splitWhen: (t<'a>, ~f: 'a => bool) => (t<'a>, t<'a>)
 */
 let unzip: t<('a, 'b)> => (t<'a>, t<'b>)
 
-/** # Iterate */
 /** Iterates over the elements of invokes `f` for each element.
 
   ## Examples
@@ -749,7 +741,6 @@ let chunksOf: (t<'a>, ~size: int) => t<t<'a>>
 */
 let sliding: (~step: int=?, t<'a>, ~size: int) => t<t<'a>>
 
-/** # Convert */
 /** Converts an array of strings into a [String](String.mdx#), placing `sep` between each string in the result.
 
   ## Examples
@@ -803,7 +794,15 @@ let toList: t<'a> => list<'a>
 */
 let toIndexedList: t<'a> => list<(int, 'a)>
 
-/** Test two arrays for equality using the provided function to test pairs of elements. */
+/** Test two arrays for equality using the provided function to test pairs of elements. 
+
+  ## Examples
+
+  ```rescript
+  Array.equal(["cat", "dog"], ["cat", "dog"], String.equal) === true
+  Array.equal(["cat", "dog"], ["parrot", "dog"], String.equal) === false
+  ```
+*/
 let equal: (t<'a>, t<'a>, ('a, 'a) => bool) => bool
 
 /** Compare two arrays using the provided `f` function to compare pairs of elements.

src/TableclothBool.resi

@@ -20,8 +20,7 @@
 */
 type t = bool
 
-/** # Create */
-/** Convert an {!Int} into a {!Bool}.
+/** Convert an [Int](Int.mdx#) into a [Bool](Bool.mdx#).
 
   ## Examples
 
@@ -34,7 +33,7 @@ type t = bool
 */
 let fromInt: int => option<bool>
 
-/** Convert a [String](String.mdx#) into a {!Bool}.
+/** Convert a [String](String.mdx#) into a [Bool](Bool.mdx#).
 
   ## Examples
 
@@ -50,7 +49,6 @@ let fromInt: int => option<bool>
 */
 let fromString: string => option<bool>
 
-/** # Basic operations */
 /** The exclusive or operator.
 
   Returns `true` if *exactly one* of its operands is `true`.
@@ -66,7 +64,7 @@ let fromString: string => option<bool>
 */
 let xor: (bool, bool) => bool
 
-/** Negate a [bool].
+/** Negate a `bool`.
 
   ## Examples
 
@@ -77,7 +75,7 @@ let xor: (bool, bool) => bool
 */
 let not: t => bool
 
-/** The logical conjunction [AND] operator.
+/** The logical conjunction `AND` operator.
 
   Returns `true` if *both* of its operands are `true`.
   If the 'left' operand evaluates to `false`, the 'right' operand is not evaluated.
@@ -93,8 +91,7 @@ let not: t => bool
 */
 let and_: (bool, bool) => bool
 
-/** # Convert */
-/** Convert a [bool] to a [String](String.mdx#)
+/** Convert a `bool` to a [String](String.mdx#)
 
   ## Examples
 
@@ -105,7 +102,7 @@ let and_: (bool, bool) => bool
 */
 let toString: bool => string
 
-/** Convert a [bool] to an {!Int}.
+/** Convert a `bool` to an [Int](Int.mdx#).
 
   ## Examples
 
@@ -116,8 +113,7 @@ let toString: bool => string
 */
 let toInt: bool => int
 
-/** {1 Compare} */
-/** Test for the equality of two [bool] values.
+/** Test for the equality of two `bool` values.
 
   ## Examples
 
@@ -129,7 +125,7 @@ let toInt: bool => int
 */
 let equal: (bool, bool) => bool
 
-/** Compare two [bool] values.
+/** Compare two `bool` values.
 
   ## Examples
 

src/TableclothChar.resi

@@ -10,23 +10,15 @@
   *not Unicode*. 
   
   Note that in Rescript source code you can include only the characters from 0-127 range. 
-  Full list of available characters is available {{: https://www.w3schools.com/charsets/ref_html_ascii.asp } here}.
+  Full list of available characters is available [here](https://www.w3schools.com/charsets/ref_html_ascii.asp).
 
   Characters from 128-255 range can still be handled, but only as codes.
 */
 type t = char
 
-/** # Create
+/** Convert an ASCII [code point](https://en.wikipedia.org/wiki/Code_point) to a character.
 
-  You can also create a {!Char} using single quotes:
-
-  ```rescript
-  let char = 'c'
-  ```
-*/
-/** Convert an ASCII {{: https://en.wikipedia.org/wiki/Code_point } code point } to a character.
-
-  The full range of extended ASCII is from `0` to [255].
+  The full range of extended ASCII is from `0` to `255`.
   For numbers outside that range, you get `None`.
 
   ## Examples
@@ -42,7 +34,7 @@ let fromCode: int => option<char>
 
 /** Converts a string to character. 
 
-  Returns `None` when the [string] isn't of length one.
+  Returns `None` when the `string` isn't of length one.
 
   ## Examples
 
@@ -131,9 +123,9 @@ let isDigit: char => bool
 */
 let isAlphanumeric: char => bool
 
-/** Detect if a character is a {{: https://en.wikipedia.org/wiki/ASCII#Printable_characters } printable } character
+/** Detect if a character is a [printable](https://en.wikipedia.org/wiki/ASCII#Printable_characters) character
 
-  A Printable character has a {!Char.toCode} in the range 32 to 127, inclusive ([' '] to ['~']).
+  A Printable character has a [Char.toCode](Char.mdx#toCode) in the range 32 to 127, inclusive (`' '` to `'~'`).
 
   ## Examples
 
@@ -148,12 +140,12 @@ let isAlphanumeric: char => bool
 let isPrintable: char => bool
 
 /** Detect one of the following characters:
-  - ['\t'] (tab)
-  - ['\n'] (newline)
-  - ['\011'] (vertical tab)
-  - ['\012'] (form feed)
-  - ['\r'] (carriage return)
-  - [' '] (space)
+  - `'\t'` (tab)
+  - `'\n'` (newline)
+  - `'\011'` (vertical tab)
+  - `'\012'` (form feed)
+  - `'\r'` (carriage return)
+  - `' '` (space)
 
   ## Examples
 
@@ -190,7 +182,7 @@ let toLowercase: char => char
 */
 let toUppercase: char => char
 
-/** Convert [char] to the corresponding ASCII {{: https://en.wikipedia.org/wiki/Code_point } code point}.
+/** Convert `char` to the corresponding ASCII [code point](https://en.wikipedia.org/wiki/Code_point).
 
   ## Examples
 
@@ -201,7 +193,7 @@ let toUppercase: char => char
 */
 let toCode: char => int
 
-/** Convert a character into a [string].
+/** Convert a character into a `string`.
 
   ## Examples
 
@@ -213,28 +205,28 @@ let toCode: char => int
 */
 let toString: char => string
 
-/** Converts a digit character to its corresponding {!Int}.
+/** Converts a digit character to its corresponding [Int](Int.mdx#).
 
   Returns `None` when the character isn't a digit.
 
   ## Examples
 
   ```rescript
-  Char.toDigit("7") == Some(7)
-  Char.toDigit("0") == Some(0)
-  Char.toDigit("A") == None
-  Char.toDigit("") == None
+  Char.toDigit('7') == Some(7)
+  Char.toDigit('0') == Some(0)
+  Char.toDigit('A') == None
+  Char.toDigit('') == None
   ```
 */
 let toDigit: char => option<int>
 
-/** Test two {!Char}s for equality */
+/** Test two [Char](Char.mdx#)s for equality */
 let equal: (t, t) => bool
 
-/** Compare two {!Char}s */
+/** Compare two [Char](Char.mdx#)s */
 let compare: (t, t) => int
 
-/** The unique identity for {!Comparator} */
+/** The unique identity for [Comparator](Comparator.mdx#) */
 type identity
 
 let comparator: TableclothComparator.t<t, identity>

src/TableclothComparator.resi

@@ -1,6 +1,6 @@
-/** Comparator provide a way for custom data structures to be used with {!Map}s and {!Set}s.
+/** Comparator provide a way for custom data structures to be used with [Map](Map.mdx#)s and [Set](Set.mdx#)s.
 
-  Say we have a module [Book] which we want to be able to create a {!Set} of
+  Say we have a module [Book] which we want to be able to create a [Set](Set.mdx#) of
 
   ```rescript
   module Book = {
@@ -13,9 +13,9 @@
   }
   ```
 
-  First we need to make our module conform to the {!S} signature.
+  First we need to make our module conform to the [S](#S) signature.
 
-  This can be done by using the {!Make} functor.
+  This can be done by using the [Make](Make.mdx#) functor.
 
   ```rescript
   module Book = {
@@ -44,19 +44,19 @@
   ```
 */
 module type T = {
-  /** T represents the input for the {!Make} functor. */
+  /** T represents the input for the [Make](Make.mdx#) functor. */
   type t
 
   let compare: (t, t) => int
 }
 
 type t<'a, 'identity>
 
-/** This just is an alias for {!t}.  */
+/** This just is an alias for [t](#t).  */
 type comparator<'a, 'identity> = t<'a, 'identity>
 
 module type S = {
-  /** The output type of {!Make}.  */
+  /** The output type of [Make](Make.mdx#).  */
   type t
 
   type identity
@@ -65,11 +65,11 @@ module type S = {
 }
 
 @ocaml.doc(
-  " A type alias that is useful typing functions which accept first class modules like {!Map.empty} or {!Set.fromArray}. "
+  " A type alias that is useful typing functions which accept first class modules like [Map.empty](Map.mdx#empty) or [Set.fromArray](Set.mdx#fromArray). "
 )
 type s<'a, 'identity> = module(S with type identity = 'identity and type t = 'a)
 
-/** Create a new comparator by providing a module which satisifies {!T}.
+/** Create a new comparator by providing a module which satisifies [T](#T).
 
   ## Examples
 

src/TableclothContainer.res

@@ -3,7 +3,7 @@
 */
 module type Sum = {
   /** Modules which conform to this signature can be used with functions like
-      {!Array.sum} or {!List.sum}.
+      [Array.sum](Array.mdx#sum) or [List.sum](List.mdx#sum).
   */
   type t