Document ignore() (#570)

Author: kevanstannard

misc_docs/syntax/builtinfunctions_ignore.mdx

@@ -0,0 +1,35 @@
+---
+id: "ignore-function"
+keywords: ["ignore"]
+name: "ignore"
+summary: "This is the `ignore()` function."
+category: "builtinfunctions"
+---
+
+The `ignore()` function discards the value of its argument and returns `()`.
+
+### Examples
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+mySideEffect()->Promise.catch(handleError)->ignore
+
+Js.Global.setTimeout(myFunc, 1000)->ignore
+```
+
+```js
+$$Promise.$$catch(mySideEffect(), function (prim) {
+  return handleError(prim);
+});
+
+setTimeout(function (prim) {
+  myFunc();
+}, 1000);
+```
+
+</CodeTab>
+
+### References
+
+* [The ignore() function](/docs/manual/latest/function#the-ignore-function)

pages/docs/manual/latest/function.mdx

@@ -409,33 +409,36 @@ add(1, 2);
 
 </CodeTab>
 
-If you need to call a curried function with a single unit `()` argument, you can use the `ignore()` function:
+If you write down the uncurried function's type, you'll add a dot there as well.
+
+**Note**: both the declaration site and the call site need to have the uncurry annotation. That's part of the guarantee/requirement.
+
+**This feature seems trivial**, but is actually one of our most important features, as a primarily functional language. We encourage you to use it if you'd like to remove any mention of `Curry` runtime in the JS output.
+
+## The ignore() Function
+
+Occasionally you may want to ignore the return value of a function. ReScript provides an `ignore()` function that discards the value of its argument and returns `()`:
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
-```res example
-let echo = (. a) => a
+```res
+mySideEffect()->Promise.catch(handleError)->ignore
 
-echo(. ignore())
+Js.Global.setTimeout(myFunc, 1000)->ignore
 ```
 
 ```js
-function echo(a) {
-  return a;
-}
+$$Promise.$$catch(mySideEffect(), function (prim) {
+  return handleError(prim);
+});
 
-echo(undefined);
+setTimeout(function (prim) {
+  myFunc();
+}, 1000);
 ```
 
 </CodeTab>
 
-
-If you write down the uncurried function's type, you'll add a dot there as well.
-
-**Note**: both the declaration site and the call site need to have the uncurry annotation. That's part of the guarantee/requirement.
-
-**This feature seems trivial**, but is actually one of our most important features, as a primarily functional language. We encourage you to use it if you'd like to remove any mention of `Curry` runtime in the JS output.
-
 ## Tips & Tricks
 
 Cheat sheet for the function syntaxes:

src/SyntaxLookup.mjs

@@ -29,30 +29,34 @@ function toString(t) {
         return "Operators";
     case /* LanguageConstructs */2 :
         return "Language Constructs";
-    case /* ExtensionPoints */3 :
+    case /* BuiltInFunctions */3 :
+        return "Built In Functions";
+    case /* ExtensionPoints */4 :
         return "Extension Points";
-    case /* SpecialValues */4 :
+    case /* SpecialValues */5 :
         return "Special Values";
-    case /* Other */5 :
+    case /* Other */6 :
         return "Other";
 
   }
 }
 
 function fromString(s) {
   switch (s) {
+    case "builtinfunctions" :
+        return /* BuiltInFunctions */3;
     case "decorators" :
         return /* Decorators */0;
     case "extensionpoints" :
-        return /* ExtensionPoints */3;
+        return /* ExtensionPoints */4;
     case "languageconstructs" :
         return /* LanguageConstructs */2;
     case "operators" :
         return /* Operators */1;
     case "specialvalues" :
-        return /* SpecialValues */4;
+        return /* SpecialValues */5;
     default:
-      return /* Other */5;
+      return /* Other */6;
   }
 }
 
@@ -233,9 +237,10 @@ function SyntaxLookup(Props) {
         /* Decorators */0,
         /* Operators */1,
         /* LanguageConstructs */2,
-        /* ExtensionPoints */3,
-        /* SpecialValues */4,
-        /* Other */5
+        /* BuiltInFunctions */3,
+        /* ExtensionPoints */4,
+        /* SpecialValues */5,
+        /* Other */6
       ], (function (cat) {
           return [
                   toString(cat),

src/SyntaxLookup.res

@@ -31,13 +31,21 @@ let requireSyntaxFile: string => MdxComp.t = %raw(`
 `)
 
 module Category = {
-  type t = Decorators | Operators | LanguageConstructs | ExtensionPoints | SpecialValues | Other
+  type t =
+    | Decorators
+    | Operators
+    | LanguageConstructs
+    | BuiltInFunctions
+    | ExtensionPoints
+    | SpecialValues
+    | Other
 
   let toString = t =>
     switch t {
     | Decorators => "Decorators"
     | Operators => "Operators"
     | ExtensionPoints => "Extension Points"
+    | BuiltInFunctions => "Built In Functions"
     | LanguageConstructs => "Language Constructs"
     | SpecialValues => "Special Values"
     | Other => "Other"
@@ -46,10 +54,11 @@ module Category = {
   let fromString = (s: string): t => {
     switch s {
     | "decorators" => Decorators
-    | "specialvalues" => SpecialValues
     | "operators" => Operators
     | "languageconstructs" => LanguageConstructs
+    | "builtinfunctions" => BuiltInFunctions
     | "extensionpoints" => ExtensionPoints
+    | "specialvalues" => SpecialValues
     | _ => Other
     }
   }
@@ -237,6 +246,7 @@ let make = () => {
       Decorators,
       Operators,
       LanguageConstructs,
+      BuiltInFunctions,
       ExtensionPoints,
       SpecialValues,
       Other,