From a532a6e010f7964dfc17af5770c92edbe2e5fb3b Mon Sep 17 00:00:00 2001
From: joostdecock <joost@joost.at>
Date: Sun, 11 Jun 2023 15:57:16 +0200
Subject: [PATCH] feat(markdown): Docs for utils.mergeOptions()

---
 markdown/dev/reference/api/en.md              |  1 +
 .../api/part/config/options/pct/toabs/en.md   |  9 ++++++-
 .../reference/api/utils/mergeoptions/en.md    | 27 +++++++++++++++++++
 3 files changed, 36 insertions(+), 1 deletion(-)
 create mode 100644 markdown/dev/reference/api/utils/mergeoptions/en.md

diff --git a/markdown/dev/reference/api/en.md b/markdown/dev/reference/api/en.md
index 22e71c3ee43..f9fb71d4d66 100644
--- a/markdown/dev/reference/api/en.md
+++ b/markdown/dev/reference/api/en.md
@@ -74,6 +74,7 @@ The following named exports are **utility methods**:
 | `lineIntersectsCircle`    | See the [lineIntersectsCircle](/reference/api/utils/lineintersectscircle) documentation |
 | `lineIntersectsCurve`     | See the [lineIntersectsCurve](/reference/api/utils/lineintersectscurve) documentation |
 | `linesIntersect`          | See the [linesIntersect](/reference/api/utils/linesintersect) documentation |
+| `mergeOptions`            | See the [mergeOptions](/reference/api/utils/mergeoptions) documentation |
 | `pctBasedOn`              | See the [pctBasedOn](/reference/api/utils/pctbasedon) documentation |
 | `pointOnBeam`             | See the [pointOnBeam](/reference/api/utils/pointonbeam) documentation |
 | `pointOnCurve`            | See the [pointOnCurve](/reference/api/utils/pointoncurve) documentation |
diff --git a/markdown/dev/reference/api/part/config/options/pct/toabs/en.md b/markdown/dev/reference/api/part/config/options/pct/toabs/en.md
index 3b20d5df34a..f32d3dbf4ff 100644
--- a/markdown/dev/reference/api/part/config/options/pct/toabs/en.md
+++ b/markdown/dev/reference/api/part/config/options/pct/toabs/en.md
@@ -17,16 +17,23 @@ The `toAbs` property should hold a function with the following
 signature:
 
 ```js
-function toAbs(percentage, settings) {
+function toAbs(percentage, settings, mergeOptions) {
   // return value in millimeter here
 }
 ```
 
 The first parameter is the percentage value provided by the user (for example
 `0.5` for `50%`).
+
 The second parameter holds the pattern's [settings](/reference/settings) object
 which holds -- among other things -- the measurements provided by the user.
 
+The third parameter should be the return value of
+[utils.mergeOptions()](/reference/api/utils/mergeoptions), which provides an
+object with all option values populated. Although this parameter is not
+required for simple values based on measurements, it is often required when the
+result depends on several options.
+
 ## Example
 
 In our example above, let's say that the `chestEase` option is
diff --git a/markdown/dev/reference/api/utils/mergeoptions/en.md b/markdown/dev/reference/api/utils/mergeoptions/en.md
new file mode 100644
index 00000000000..e38a054f3a5
--- /dev/null
+++ b/markdown/dev/reference/api/utils/mergeoptions/en.md
@@ -0,0 +1,27 @@
+---
+title: utils.mergeOptions()
+---
+
+The `utils.mergeOptions()` function merges the user-provided options with the
+options from the pattern configuration.
+
+## Signature
+
+```js
+float deg2rad(object settings, object optionsConfig)
+```
+
+## Notes
+
+Typically the only options that are passed as part of settings to the pattern
+are those that differ from the defaults.  This means that if you want to check
+an option outside a draft method, you need to check whether the option is set,
+and if it's not get the default value from the pattern config. Furthermore,
+where the default is stored and whether or not it should be further transformed
+depends on the option type.
+
+This method exists to facilitate this. You pass it the user-provided settings,
+and the pattern config options key, and it will return an object where all
+options are populated with the user-provided values, or their defaults if the
+user did not provide any input.
+