Syntax lookup: labeled and optional args (#888)

* Syntax Lookup: Add labeled args

* Syntax Lookup: Add optional args

* Syntax Lookup: Make send.pipe deprecated

* Syntax Lookup: Default labeled args

* Syntax Lookup: Mention partial application and order of labeled args

Author: fhammerschmidt

misc_docs/syntax/decorator_send_pipe.mdx

@@ -4,6 +4,7 @@ keywords: ["send", "pipe", "decorator"]
 name: "@bs.send.pipe"
 summary: "This is the `@bs.send.pipe` decorator."
 category: "decorators"
+status: "deprecated"
 ---
 
 > Removed since compiler version 10.0. Use the [@send](https://rescript-lang.org/docs/manual/latest/bind-to-js-function) decorator instead.

misc_docs/syntax/language_labeled_argument.mdx

@@ -0,0 +1,69 @@
+---
+id: "labeled-argument"
+keywords: ["labeled", "argument"]
+name: "~arg"
+summary: "This is a `labeled argument`."
+category: "languageconstructs"
+---
+
+When declaring a function, arguments can be prefixed with `~` which means that they can and need to be called by their name, not the argument position. This is especially useful to differentiate them more easily if they are of the same type.
+
+### Example
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res prelude
+let calculateDistance = (~x1, ~y1, ~x2, ~y2) => {
+  Math.sqrt((x1 -. x2) ** 2. +. (y1 -. y2) ** 2.)
+}
+
+calculateDistance(~x1=6., ~y1=8., ~x2=3., ~y2=4.) 
+```
+
+```js
+function calculateDistance(x1, y1, x2, y2) {
+  return Math.sqrt(Math.pow(x1 - x2, 2) + Math.pow(y1 - y2, 2));
+}
+
+calculateDistance(6, 8, 3, 4);
+```
+
+</CodeTab>
+
+Labeled arguments can be provided in any order:
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+calculateDistance(~x1=6., ~x2=3., ~y1=8., ~y2=4.) 
+```
+
+```js
+calculateDistance(6, 8, 3, 4);
+```
+
+</CodeTab>
+
+This also works together with partial application:
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+let calcY = calculateDistance(~x1=6., ~x2=3., ...)
+calcY(~y1=8., ~y2=4.)
+```
+
+```js
+function calcY(none, extra) {
+  return calculateDistance(6, none, 3, extra);
+}
+
+calcY(8, 4);
+```
+
+</CodeTab>
+
+### References
+
+* [Labeled Arguments](/docs/manual/latest/function#labeled-arguments)
+* [Function Syntax Cheatsheet](/docs/manual/latest/function#tips--tricks)

misc_docs/syntax/language_optional_labeled_argument.mdx

@@ -0,0 +1,85 @@
+---
+id: "optional-labeled-argument"
+keywords: ["optional", "labeled", "argument"]
+name: "~arg=?"
+summary: "This is an `optional labeled argument`."
+category: "languageconstructs"
+---
+
+Labeled arguments, i.e. arguments that are prefixed with `~`, can be suffixed with `=?` to denote that they are optional. Thus, they can be
+omitted when calling the function.
+
+### Example
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+let print = (text, ~logLevel=?) => {
+  switch logLevel {
+  | Some(#error) => Console.error(text)
+  | _ => Console.log(text)
+  }
+}
+
+print("An info")
+print("An error", ~logLevel=#error)
+```
+
+```js
+function print(text, logLevel) {
+  if (logLevel === "error") {
+    console.error(text);
+  } else {
+    console.log(text);
+  }
+}
+
+print("An info", undefined);
+
+print("An error", "error");
+```
+
+</CodeTab>
+
+Optional labeled arguments can also hold a default value.
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+let print = (text, ~logLevel=#info) => {
+  switch logLevel {
+  | #error => Console.error(text)
+  | #warn => Console.warn(text)
+  | #info => Console.log(text)
+  }
+}
+
+print("An info")
+print("A warning", ~logLevel=#warn)
+```
+
+```js
+function print(text, logLevelOpt) {
+  var logLevel = logLevelOpt !== undefined ? logLevelOpt : "info";
+  if (logLevel === "warn") {
+    console.warn(text);
+  } else if (logLevel === "error") {
+    console.error(text);
+  } else {
+    console.log(text);
+  }
+}
+
+print("An info", undefined);
+
+print("A warning", "warn");
+```
+
+</CodeTab>
+
+### References
+
+* [Labeled Arguments](/docs/manual/latest/function#labeled-arguments)
+* [Optional Labeled Arguments](/docs/manual/latest/function#optional-labeled-arguments)
+* [Labeled Argument with Default Value](/docs/manual/latest/function#optional-with-default-value)
+* [Function Syntax Cheatsheet](/docs/manual/latest/function#tips--tricks)