Syntax lookup overhaul + add missing constructs

Author: fhammerschmidt

markdown-pages/docs/manual/overview.mdx

@@ -57,13 +57,13 @@ order: 1
 
 ### Number
 
-| JavaScript  | ReScript     |
-| ----------- | ------------ |
-| `3`         | Same \*      |
-| `3.1415`    | Same         |
-| `3 + 4`     | Same         |
-| `3.0 + 4.5` | `3.0 +. 4.5` |
-| `5 % 3`     | `mod(5, 3)`  |
+| JavaScript  | ReScript |
+| ----------- | -------- |
+| `3`         | Same \*  |
+| `3.1415`    | Same     |
+| `3 + 4`     | Same     |
+| `3.0 + 4.5` | Same     |
+| `5 % 3`     | Same     |
 
 \* JS has no distinction between integer and float.
 
@@ -235,7 +235,7 @@ The last expression of a block delimited by `{}` implicitly returns (including f
 | ------------------------------- | ------------------------------------ | ------------------------------------------ |
 | String                          | `"Hello"`                            | `"Hello"`                                  |
 | String Interpolation            | `` `Hello ${message}` ``             | `"Hello " + message`                       |
-| Character (disrecommended)      | `'x'`                                | `120` (char code)                          |
+| Character (discouraged)         | `'x'`                                | `120` (char code)                          |
 | Integer                         | `23`, `-23`                          | `23`, `-23`                                |
 | Float                           | `23.0`, `-23.0`                      | `23.0`, `-23.0`                            |
 | Integer Addition                | `23 + 1`                             | `23 + 1`                                   |
@@ -247,7 +247,7 @@ The last expression of a block delimited by `{}` implicitly returns (including f
 | Comparison                      | `>`, `<`, `>=`, `<=`                 | `>`, `<`, `>=`, `<=`                       |
 | Boolean operation               | `!`, `&&`, `\|\|`                    | `!`, `&&`, `\|\|`                          |
 | Shallow and deep Equality       | `===`, `==`                          | `===`, `==`                                |
-| List (disrecommended)           | `list{1, 2, 3}`                      | `{hd: 1, tl: {hd: 2, tl: {hd: 3, tl: 0}}}` |
+| List (discouraged)              | `list{1, 2, 3}`                      | `{hd: 1, tl: {hd: 2, tl: {hd: 3, tl: 0}}}` |
 | List Prepend                    | `list{a1, a2, ...oldList}`           | `{hd: a1, tl: {hd: a2, tl: theRest}}`      |
 | Array                           | `[1, 2, 3]`                          | `[1, 2, 3]`                                |
 | Record                          | `type t = {b: int}; let a = {b: 10}` | `var a = {b: 10}`                          |

markdown-pages/docs/manual/primitive-types.mdx

@@ -148,6 +148,12 @@ ReScript's `true/false` compiles into a JavaScript `true/false`.
 
 32-bits, truncated when necessary. We provide the usual operations on them: `+`, `-`, `*`, `/`, etc. See [Int](/docs/manual/api/stdlib/int) for helper functions.
 
+Integer operators include `+`, `-`, `*`, `/`, `**`, and `%`.
+
+`%` keeps the familiar `mod` naming, but its semantics are remainder (same behavior as JavaScript `%`).
+
+Bitwise operators for `int`: `~~~`, `&&&`, `|||`, `^^^`, `<<`, `>>`, `>>>`.
+
 **Be careful when you bind to JavaScript numbers!** Since ReScript integers have a much smaller range than JavaScript numbers, data might get lost when dealing with large numbers. In those cases it’s much safer to bind the numbers as **float**. Be extra mindful of this when binding to JavaScript Dates and their epoch time.
 
 To improve readability, you may place underscores in the middle of numeric literals such as `1_000_000`. Note that underscores can be placed anywhere within a number, not just every three digits.
@@ -156,6 +162,8 @@ To improve readability, you may place underscores in the middle of numeric liter
 
 Float requires other operators: `+.`, `-.`, `*.`, `/.`, etc. Like `0.5 +. 0.6`. See [Float](/docs/manual/api/stdlib/float) for helper functions.
 
+Float also supports `**` (exponentiation) and `%` (remainder semantics).
+
 As with integers, you may use underscores within literals to improve readability.
 
 ### Int-to-Float Coercion
@@ -179,7 +187,7 @@ var result = 1 + 2;
 **Since 11.1**
 
 For values which are too large to be represented by Int or Float, there is the `bigint` primitive type.
-We provide the usual operations on them: `+`, `-`, `*`, `/`, etc. See [BigInt](/docs/manual/api/stdlib/bigint) for helper functions.
+We provide the usual operations on them: `+`, `-`, `*`, `/`, `**`, `%`, etc. See [BigInt](/docs/manual/api/stdlib/bigint) for helper functions.
 
 A `bigint` number is denoted by a trailing `n` like so: `42n`.
 
@@ -209,28 +217,26 @@ It also supports all the bitwise operations, except unsigned shift right (`>>>`)
 ```res example
 open! BigInt
 
-let a = land(1n, 1n)
-let b = lor(1n, 1n)
-let c = lxor(1n, 1n)
-let d = lnot(1n)
-let e = lsl(1n, 1n)
-let f = asr(1n, 1n)
+let a = 5n &&& 3n
+let b = 5n ||| 2n
+let c = 5n ^^^ 1n
+let d = ~~~5n
+let e = 5n << 1n
+let f = 5n >> 1n
 ```
 
 ```js
-var Js_bigint = require("./stdlib/js_bigint.js");
-
-var a = 1n & 1n;
+var a = 5n & 3n;
 
-var b = 1n | 1n;
+var b = 5n | 2n;
 
-var c = 1n ^ 1n;
+var c = 5n ^ 1n;
 
-var d = Js_bigint.lnot(1n);
+var d = ~5n;
 
-var e = 1n << 1n;
+var e = 5n << 1n;
 
-var f = 1n >> 1n;
+var f = 5n >> 1n;
 ```
 
 </CodeTab>

markdown-pages/syntax-lookup/language_and.mdx

@@ -0,0 +1,50 @@
+---
+id: "and"
+keywords: ["and", "let rec and", "type rec and", "mutual recursion"]
+name: "and"
+summary: "This is the `and` keyword for mutually recursive definitions."
+category: "languageconstructs"
+---
+
+Use `and` to define multiple items in one mutually-recursive group.
+
+### Example 1: `let rec ... and ...`
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+let rec isEven = n => n == 0 || isOdd(n - 1)
+and isOdd = n => n != 0 && isEven(n - 1)
+```
+
+```js
+function isEven(n) {
+  return n === 0 || isOdd((n - 1) | 0);
+}
+
+function isOdd(n) {
+  return n !== 0 && isEven((n - 1) | 0);
+}
+```
+
+</CodeTab>
+
+### Example 2: `type rec ... and ...`
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+type rec expr = Add(expr, term) | Term(term)
+and term = Int(int)
+```
+
+```js
+// Type declarations are erased from JavaScript output.
+```
+
+</CodeTab>
+
+### References
+
+- [Recursive Functions](../docs/manual/function.mdx#recursive-functions)
+- [Type](../docs/manual/type.mdx)

markdown-pages/syntax-lookup/language_async.mdx

@@ -3,7 +3,7 @@ id: "async"
 keywords: ["async"]
 name: "async"
 summary: "This is the `async` keyword."
-category: "languageconstructs"
+category: "languagecontrolflow"
 ---
 
 **Since 10.1**

markdown-pages/syntax-lookup/language_attached_doc_comment.mdx

@@ -0,0 +1,30 @@
+---
+id: "attached-doc-comment"
+keywords: ["doc comment", "attached doc comment", "/**"]
+name: "/** ... */"
+summary: "This is the `attached doc comment` syntax."
+category: "languagecomments"
+---
+
+Use an attached doc comment directly before a value or type declaration.
+
+### Example
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+/** Returns the full name. */
+let fullName = (first, last) => first ++ " " ++ last
+```
+
+```js
+function fullName(first, last) {
+  return first + " " + last;
+}
+```
+
+</CodeTab>
+
+### References
+
+- [Overview](../docs/manual/overview.mdx#comments)

markdown-pages/syntax-lookup/language_await.mdx

@@ -3,7 +3,7 @@ id: "await"
 keywords: ["await"]
 name: "await"
 summary: "This is the `await` keyword."
-category: "languageconstructs"
+category: "languagecontrolflow"
 ---
 
 **Since 10.1**

markdown-pages/syntax-lookup/language_block_comment.mdx

@@ -0,0 +1,30 @@
+---
+id: "block-comment"
+keywords: ["comment", "block comment", "/*", "*/"]
+name: "/* ... */"
+summary: "This is the `block comment` syntax."
+category: "languagecomments"
+---
+
+Use `/* ... */` for multi-line comments.
+
+### Example
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+/*
+  This is a block comment.
+*/
+let greeting = "hello"
+```
+
+```js
+var greeting = "hello";
+```
+
+</CodeTab>
+
+### References
+
+- [Overview](../docs/manual/overview.mdx#comments)

markdown-pages/syntax-lookup/language_char_literal.mdx

@@ -3,7 +3,7 @@ id: "char-literal"
 keywords: ["char"]
 name: "' '"
 summary: "This is the `char` literal syntax."
-category: "languageconstructs"
+category: "languagepatternsvalues"
 ---
 
 A `char` literal is composed of two **single** quotes. Double quotes are reserved for the `string` type. Note that `char` is essentially an integer in JS since version 10.0.

markdown-pages/syntax-lookup/language_covariant_type_parameter.mdx

@@ -0,0 +1,31 @@
+---
+id: "covariant-type-parameter"
+keywords: ["<+a>", "+'a", "covariant", "variance", "type parameter"]
+name: "<+a>"
+summary: "This is a `covariant type parameter` annotation."
+category: "languagetypes"
+---
+
+Use a `+` variance annotation on a type parameter to mark it as covariant.
+
+### Example
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+type source<+'a> = unit => 'a
+
+let fromValue = (x: 'a): source<'a> => () => x
+```
+
+```js
+function fromValue(x) {
+  return (_) => x;
+}
+```
+
+</CodeTab>
+
+### References
+
+- [Type Parameters](../docs/manual/type.mdx#type-parameter-aka-generic)

markdown-pages/syntax-lookup/language_dict.mdx

@@ -3,7 +3,7 @@ id: "dict"
 keywords: ["dict"]
 name: "dict"
 summary: "This is the `dict{}` syntax"
-category: "languageconstructs"
+category: "languagetypes"
 ---
 
 > Available in v12+