Merge pull request #850 from rescript-association/todo-warn-error

Add docs for %todo and -warn-error

Author: fhammerschmidt

compilers/package-lock.json

@@ -10,7 +10,7 @@
     "rescript-1000": "npm:rescript@10.0.0",
     "rescript-1010": "npm:rescript@10.1.0",
     "rescript-1100": "npm:rescript@11.0.0",
-    "rescript-1110": "npm:rescript@11.1.0-rc.6",
+    "rescript-1110": "npm:rescript@11.1.0-rc.8",
     "rescript-820": "npm:bs-platform@8.2.0",
     "rescript-902": "npm:bs-platform@9.0.2",
     "rescript-912": "npm:rescript@9.1.2"

compilers/package.json

@@ -0,0 +1,48 @@
+---
+id: "todo"
+keywords: ["todo"]
+name: "%todo"
+summary: "This is the `todo` extension point."
+category: "extensionpoints"
+---
+
+**Since 11.1**
+
+`%todo` is used to tell the compiler that some code still needs to be implemented.
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+let implementMeLater = (): string => %todo("This should return a string eventually.")
+
+let x = implementMeLater()
+
+Console.log(x->String.includes("x"))
+```
+
+```js
+var Js_exn = require("./stdlib/js_exn.js");
+
+function implementMeLater() {
+  return Js_exn.raiseError("playground.res:1:37-42 - Todo: This should return a string eventually.");
+}
+
+var x = Js_exn.raiseError("playground.res:1:37-42 - Todo: This should return a string eventually.");
+
+console.log(x.includes("x"));
+```
+
+</CodeTab>
+
+It can also be used without a text message:
+
+```res
+let implementMeLater = (): string => %todo
+```
+
+This will crash when executed. We suggest to [promote the warning to an error](/docs/manual/latest/build-overview#compile-with-stricter-errors-in-ci) when building for production.
+
+### References
+
+* [Stricter compilation in CI](/docs/manual/latest/build-overview#compile-with-stricter-errors-in-ci)
+* [Extension Point Attributes](/docs/manual/latest/attribute#extension-point)

misc_docs/syntax/extension_todo.mdx

@@ -69,3 +69,15 @@ If you ever get into a stale build for edge-case reasons, use:
 ```sh
 rescript clean
 ```
+
+## Compile with stricter errors in CI
+
+**Since 11.1**
+
+You may want to compile your project with stricter rules for production, than when developing. With the `-warn-error` build flag, this can easily be done, for instance in a continuous integration script. E.g.:
+
+```sh
+rescript -warn-error +110
+```
+
+Here, warning number 110, which is triggered when a [`%todo`](/syntax-lookup#todo) has been found, gets promoted to an error. The full list of warning numbers can be found [here](/docs/manual/latest/warning-numbers).

pages/docs/manual/latest/build-overview.mdx

@@ -51,10 +51,9 @@ This is a glossary with examples. All the features are described by later pages.
 
 - [`%debugger`](embed-raw-javascript#debugger)
 - [`%external`](bind-to-global-js-values#special-global-values)
-<!-- - `%node` -->
-<!-- - `%obj` -->
 - [`%raw`](embed-raw-javascript#paste-raw-js-code)
 - [`%re`](primitive-types#regular-expression)
+- [`%todo`](/syntax-lookup#todo)
 
 ## Raw JS
 

pages/docs/manual/latest/interop-cheatsheet.mdx

@@ -70,6 +70,7 @@ let numeric = [
   (107, "Integer literal exceeds the range of representable integers of type int"),
   (108, "Uninterpreted delimiters (for unicode)"),
   (109, "Toplevel expression has unit type"),
+  (110, "Todo found"),
 ]
 
 let letterAll = numeric->Belt.Array.map(fst)
@@ -226,7 +227,12 @@ module Parser = {
     | _ => ()
     }
 
-    ret
+    ret->Belt.SortArray.stableSortBy((v1, v2) => {
+      let a = v1.flag->Belt.Int.fromString
+      let b = v2.flag->Belt.Int.fromString
+
+      compare(a, b)
+    })
   }
 
   let parse = (input: string): result<array<token>, string> =>