docs: LSDV-4754: Update Audio documentation to point to v3 (#1242)

* docs: LSDV-4574: Update Audio documentation to point to v3

* this apparently shouldn't be committed

* Update Paragraphs.js

* Add some comment about return type

JSDoc can't parse tuple type, so let it be just `Array` with comment

* Escape tags in Labels and Choices docs

* "publicly" spelling

---------

Co-authored-by: hlomzik <hlomzik@gmail.com>

Author: bmartel

src/tags/control/Choices.js

@@ -27,7 +27,7 @@ const { Option } = Select;
 /**
  * The `Choices` tag is used to create a group of choices, with radio buttons or checkboxes. It can be used for single or multi-class classification. Also, it is used for advanced classification tasks where annotators can choose one or multiple answers.
  *
- * Choices can have dynamic value to load labels from task. This task data should contain a list of options to create underlying <Choice>s. All the parameters from options will be transferred to corresponding tags.
+ * Choices can have dynamic value to load labels from task. This task data should contain a list of options to create underlying `<Choice>`s. All the parameters from options will be transferred to corresponding tags.
  *
  * The `Choices` tag can be used with any data types.
  * @example

src/tags/control/Labels/Labels.js

@@ -22,7 +22,7 @@ import './Labels.styl';
 /**
  * The `Labels` tag provides a set of labels for labeling regions in tasks for machine learning and data science projects. Use the `Labels` tag to create a set of labels that can be assigned to identified region and specify the values of labels to assign to regions.
  *
- * All types of Labels can have dynamic value to load labels from task. This task data should contain a list of options to create underlying <Label>s. All the parameters from options will be transferred to corresponding tags.
+ * All types of Labels can have dynamic value to load labels from task. This task data should contain a list of options to create underlying `<Label>`s. All the parameters from options will be transferred to corresponding tags.
  *
  * The Labels tag can be used with audio and text data types. Other data types have type-specific Labels tags.
  * @example

src/tags/control/MagicWand.js

@@ -49,7 +49,7 @@ import { FF_DEV_4081, isFF } from '../../utils/feature-flags';
  * `crossOrigin` attribute that a normal DOM `img` tag would
  * have ([reference])(https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/crossOrigin).
  *
- * If the image is on a public server or Google/AWS/Azure bucket that is publically readable
+ * If the image is on a public server or Google/AWS/Azure bucket that is publicly readable
  * without any authentication, you should set `crossOrigin` to `anonymous`.
  *
  * If the image is on a server or a private cloud bucket that requires authentication of any

src/tags/object/Audio.js

@@ -39,7 +39,6 @@ import { customTypes } from '../../core/CustomTypes';
  * @regions AudioRegion
  * @meta_title Audio Tag for Labeling Audio
  * @meta_description Customize Label Studio to label audio data for machine learning and data science projects.
- * @name Audio
  * @param {string} name Name of the element
  * @param {string} value Data field containing path or a URL to the audio
  * @param {string} hotkey Hotkey used to play or pause audio

src/tags/object/AudioNext/model.js

@@ -27,7 +27,6 @@ import { WS_SPEED, WS_VOLUME, WS_ZOOM_X } from './constants';
  *   <Rating name="rate-1" toName="audio-1" />
  *   <Audio name="audio-1" value="$audio" />
  * </View>
- * @name Audio
  * @meta_title Audio Tag for Audio Labeling
  * @meta_description Customize Label Studio with the Audio tag for advanced audio annotation tasks for machine learning and data science projects.
  * @param {string} name - Name of the element

src/tags/object/AudioUltra/model.js

@@ -19,7 +19,32 @@ import { WS_SPEED, WS_VOLUME, WS_ZOOM_X } from './constants';
  *
  * Use with the following data types: audio
  * @example
- * <!--Labeling configuration to label regions of audio and rate the audio sample-->
+ * <!-- Play audio on the labeling interface -->
+ * <View>
+ *   <Audio name="audio" value="$audio" />
+ * </View>
+ * @example
+ * <!-- Play audio with multichannel support -->
+ * <View>
+ *   <Audio name="audio" value="$audio" splitchannels="true" />
+ * </View>
+ * @example
+ * <!-- Audio classification -->
+ * <View>
+ *   <Audio name="audio" value="$audio" />
+ *   <Choices name="ch" toName="audio">
+ *     <Choice value="Positive" />
+ *     <Choice value="Negative" />
+ *   </Choices>
+ * </View>
+ * @example
+ * <!-- Audio transcription -->
+ * <View>
+ *   <Audio name="audio" value="$audio" />
+ *   <TextArea name="ta" toName="audio" />
+ * </View>
+ * @example
+ * <!-- Labeling configuration to label regions of audio and rate the audio sample-->
  * <View>
  *   <Labels name="lbl-1" toName="audio-1">
  *     <Label value="Guitar" />
@@ -28,28 +53,42 @@ import { WS_SPEED, WS_VOLUME, WS_ZOOM_X } from './constants';
  *   <Rating name="rate-1" toName="audio-1" />
  *   <Audio name="audio-1" value="$audio" />
  * </View>
- * @name Audio
+ * @example
+ * <!-- Sync with video -->
+ * <View>
+ *   <Video name="video-1" value="$video" sync="audio-1" />
+ *   <Labels name="lbl-1" toName="audio-1">
+ *     <Label value="Guitar" />
+ *     <Label value="Drums" />
+ *   </Labels>
+ *   <Audio name="audio-1" value="$video" sync="video-1" />
+ * </View>
+ * @example
+ * <!-- Sync with paragraphs -->
+ * <View>
+ *   <Labels name="lbl-1" toName="audio-1">
+ *     <Label value="Guitar" />
+ *     <Label value="Drums" />
+ *   </Labels>
+ *   <Audio name="audio-1" value="$audio" sync="txt-1" />
+ *   <Paragraphs audioUrl="$audio" sync="audio-1" name="txt-1" value="$text" layout="dialogue" showplayer="true" />
+ * </View>
+ * @regions AudioRegion
  * @meta_title Audio Tag for Audio Labeling
  * @meta_description Customize Label Studio with the Audio tag for advanced audio annotation tasks for machine learning and data science projects.
+ * @name Audio
  * @param {string} name - Name of the element
  * @param {string} value - Data field containing path or a URL to the audio
- * @param {boolean=} [volume=false] - Whether to show a volume slider (from 0 to 1)
- * @param {string} [defaultvolume=1] - Default volume level (from 0 to 1)
- * @param {boolean} [speed=false] - Whether to show a speed slider (from 0.5 to 3)
  * @param {string} [defaultspeed=1] - Default speed level (from 0.5 to 2)
- * @param {boolean} [zoom=true] - Whether to show the zoom slider
- * @param {string} [defaultzoom=1] - Default zoom level (from 1 to 1500)
+ * @param {string} [defaultscale=1] - Audio pane default y-scale for waveform
+ * @param {string} [defaultzoom=1] - Default zoom level for waveform (from 1 to 1500)
+ * @param {string} [defaultvolume=1] - Default volume level (from 0 to 1)
  * @param {string} [hotkey] - Hotkey used to play or pause audio
  * @param {string} [sync] object name to sync with
  * @param {string} [height=96] - Total height of the audio player
  * @param {string} [waveheight=32] - Minimum height of a waveform when in splitchannel mode with multiple channels
- * @param {string} [cursorwidth=1] - Audio pane cursor width. it's Measured in pixels.
- * @param {string} [cursorcolor=#333] - Audio pane cursor color. Color should be specify in hex decimal string
- * @param {string} [defaultscale=1] - Audio pane default y-scale for waveform
- * @param {boolean} [autocenter=true] – Always place cursor in the middle of the view
- * @param {boolean} [scrollparent=true] – Wave scroll smoothly follows the cursor
- * @param {boolean} [splitchannels=true] – Display stereo channels separately
- * @param {string} [decoder=ffmpeg] – Decoder type to use to decode audio data. ("ffmpeg" or "webaudio")
+ * @param {boolean} [splitchannels=false] - Display multichannel separately (if supported by the file)
+ * @param {string} [decoder=webaudio] - Decoder type to use to decode audio data. (`"webaudio"` or `"ffmpeg"`)
  */
 const TagAttrs = types.model({
   name: types.identifier,

src/tags/object/Paragraphs/Paragraphs.js

@@ -38,7 +38,7 @@ class HtxParagraphsView extends Component {
    * @param {HTMLElement} node
    * @param {number} offset
    * @param {boolean} [isStart=true]
-   * @return {[number, HTMLElement, number, number]}
+   * @return {Array} [offset, node, index, originalIndex]
    */
   getOffsetInPhraseElement(container, offset, isStart = true) {
     const node = this.getPhraseElement(container);