docs: Improve dynamic Choices example, add html attribute (#1220)

* Add `html` attribute to `Choices` documentation. Describe dynamic `Choices` better. Provide flags that has to be enabled in order to use them.

* Update jsdoc-to-markdown to avoid buffer errors

`create-docs` script fails on local runs because of unclear error.
Turned out it's because of buffer overflow, new version works well.

* Update lock file

* Fix typo

* One more typo

---------

Co-authored-by: Max Tkachenko <[email protected]>

Author: hlomzik

package.json

@@ -86,9 +86,9 @@
     "text-annotation"
   ],
   "dependencies": {
+    "@martel/audio-file-decoder": "2.3.15",
     "@thi.ng/rle-pack": "^2.1.6",
     "babel-plugin-istanbul": "^6.1.1",
-    "@martel/audio-file-decoder": "2.3.15",
     "babel-preset-react-app": "^9.1.1",
     "d3": "^5.16.0",
     "magic-wand-js": "^1.0.0",
@@ -150,7 +150,7 @@
     "insert-after": "^0.1.4",
     "jest": "^29.3.1",
     "jest-environment-jsdom": "^29.3.1",
-    "jsdoc-to-markdown": "^5.0.3",
+    "jsdoc-to-markdown": "^8",
     "keymaster": "*",
     "konva": "^8.1.3",
     "lint-staged": "^9.5.0",

src/tags/control/Choices.js

@@ -43,20 +43,27 @@ const { Option } = Select;
  * </View>
  *
  * @example <caption>This config with dynamic labels</caption>
+ * <!--
+ *   `Choice`s can be loaded dynamically from task data. It should be an array of objects with attributes.
+ *   `html` can be used to show enriched content, it has higher priority than `value`, however `value` will be used in the exported result.
+ *   *ff_dev_2007_dev_2008_dynamic_tag_children_250322_short* should be enabled to use dynamic options.
+ *   *ff_dev_2007_rework_choices_280322_short* should be enabled to use `html` attribute.
+ * -->
  * <View>
  *   <Audio name="audio" value="$audio" />
  *   <Choices name="transcription" toName="audio" value="$variants" />
  * </View>
  * <!-- {
  *   "data": {
  *     "variants": [
- *       { "value": "Do or doughnut. There is no try." },
- *       { "value": "Do or do not. There is no trial." },
+ *       { "value": "Do or doughnut. There is no try.", "html": "<img src='https://labelstud.io/images/logo.png'>" },
+ *       { "value": "Do or do not. There is no trial.", "html": "<h1>You can use hypertext here</h2>" },
  *       { "value": "Do or do not. There is no try." },
  *       { "value": "Duo do not. There is no try." }
  *     ]
  *   }
  * } -->
+ * 
  * @example <caption>is equivalent to this config</caption>
  * <View>
  *   <Audio name="audio" value="$audio" />

src/tags/control/Number.js

@@ -32,7 +32,7 @@ import { ReadOnlyControlMixin } from '../../mixins/ReadOnlyMixin';
  * @param {number} [min]                      - Minimum number value
  * @param {number} [max]                      - Maximum number value
  * @param {number} [step=1]                   - Step for value increment/decrement
- * @param {number} [defaultValue]             - Default number value; will be added automaticaly to result for required fields
+ * @param {number} [defaultValue]             - Default number value; will be added automatically to result for required fields
  * @param {string} [hotkey]                   - Hotkey for increasing number value
  * @param {boolean} [required=false]          - Whether to require number validation
  * @param {string} [requiredMessage]          - Message to show if validation fails

src/tags/visual/Repeater.js

@@ -2,7 +2,7 @@
 
 /**
  * Repeater Tag for annotating multiple data objects in a dynamic range with the same semantics. You can loop through data items in a python-like `for` cycle in the labeling process.
- * It repeats tags inside it for every item in a given data array from your dataset. All the occurences of `indexFlag` (default is `{{idx}}`) in parameter values will be replaced by the current index.
+ * It repeats tags inside it for every item in a given data array from your dataset. All the occurrences of `indexFlag` (default is `{{idx}}`) in parameter values will be replaced by the current index.
  * Names should always be unique, so you can use this placeholder in tag names.
  *
  * The Repeater Tag supports the `mode` property. This creates the possibility to enable pagination in repeater for performance improvement.