From 8c57547b1076f2c94e41588220feb15de8f3a42d Mon Sep 17 00:00:00 2001
From: joostdecock <joost@joost.at>
Date: Sat, 9 Mar 2024 17:32:12 +0100
Subject: [PATCH] feat (markdown): Improved flag.info docs

---
 .../reference/store-methods/flag.info/en.md   | 67 ++++++++++++++++++-
 1 file changed, 64 insertions(+), 3 deletions(-)

diff --git a/markdown/dev/reference/store-methods/flag.info/en.md b/markdown/dev/reference/store-methods/flag.info/en.md
index 394e6740ebe..8ac3ffcfdaf 100644
--- a/markdown/dev/reference/store-methods/flag.info/en.md
+++ b/markdown/dev/reference/store-methods/flag.info/en.md
@@ -18,6 +18,10 @@ pattern configuration.
 undefined Store.flag.info({
   title: 'flag:expandIsOn.t',
   desc: 'flag:expandIsOn.d',
+  notes: [
+    'sorcha:moreInfo1',
+    'sorcha:moreInfo2',
+  ],
   suggest: {
     text: 'flag:disable',
     icon: 'expand',
@@ -38,13 +42,70 @@ The example above is from our implementation, which uses the following propertie
 | `id`       | String              | An ID for this flag message. If none is provided, `title` will be used |
 | `title`    | String              | The title of the message |
 | `desc`     | String              | The description of the message |
-| `suggest.text`  | String              | Text to go on the button to implement the suggested configuration change |
-| `suggest.icon`  | String              | Icon name to go on the button to implement the suggested configuration change |
-| `suggest.update` | Object             | Object describing the changes to apply to the configuration if the user accepts the suggestion |
+| `notes`    | String or  Array of Strings | More information/notes (see [Notes](#notes))|
+| `suggest.text`  | String         | Text to go on the button to implement the suggested configuration change |
+| `suggest.icon`  | String         | Icon name to go on the button to implement the suggested configuration change. (see [suggest.icon](#suggesticon)) |
+| `suggest.update.settings` | Array | An array describing the changes to apply to the `settings` if the user accepts the suggestion. (see [suggest.update](#suggestupdate)) |
+| `suggest.update.ui` | Array | An array describing the changes to apply to the `ui` if the user accepts the suggestion. (see [suggest.update](#suggestupdate)) |
+
+### Notes
+
+Notes are optional, but allow you to add more text/content to the flag message.
+
+Unlike `desc` which can only hold a string, `notes` can hold either a string or an array of strings.
+
+Both `desc` and `notes` will be rendered as markdown.
+
+### suggest.icon
+
+An optional name of an icon. Or leave it out to not render and icon.
+The idea is that the icon helps convey the message, the following icon names are supported:
+
+- `note`
+- `info`
+- `tip`
+- `warn`
+- `error`
+- `fixme`
+- `expand`
+- `options`
+
+Any other name will be ignored.
+
+### suggest.update
 
 Note that the `suggest` object is optional. Without it, it will merely display a message to the user.
 However, when a suggest key is present, a button will be created that the user can click to accept the suggested changes.
 
+The `suggest.update` object has only two possible top-level keys: 
+
+- `settings` 
+- `ui`
+
+They both take the same parameter, an array with two elements: 
+
+```mjs
+Array [`path`, `value`]
+```
+
+This will be used to update the `settings` of the pattern, or the `ui` settings on FreeSewing.org.
+
+The way they are updated is by invoking [lodash.set](https://lodash.com/docs/4.17.15#set) on either the settings object or the ui object.
+Which means:
+
+- `path` describes the path to the value to change in dot-notation
+- `value` is the value to set
+
+So to set the `waistEase` option to `0.2`, it should look like this:
+
+```mjs
+{
+  update: {
+    settings: ['options.waistEase', 0.2]
+  }
+}
+```
+
 ## Example
 
 ```js