Update docs for HyperText/Text via stub files (#403)

* Update docs for HyperText/Text via stub files

* fix `inline` param jsdoc

Co-authored-by: smoreface <[email protected]>

* fix BrushRegion docs to be the same as in master

Co-authored-by: smoreface <[email protected]>

Author: hlomzik

src/regions/HyperTextRegion.js

@@ -0,0 +1,21 @@
+// stub file to keep HyperTextRegion docs
+
+/**
+ * @example
+ * {
+ *   "value": {
+ *     "start": "/div[1]/p[2]/text()[1]",
+ *     "end": "/div[1]/p[4]/text()[3]",
+ *     "startOffset": 2,
+ *     "endOffset": 81,
+ *     "hypertextlabels": ["Car"]
+ *   }
+ * }
+ * @typedef {Object} HyperTextRegionResult
+ * @property {Object} value
+ * @property {string} value.start xpath of the container where the region starts (xpath)
+ * @property {string} value.end xpath of the container where the region ends (xpath)
+ * @property {number} value.startOffset offset within start container
+ * @property {number} value.endOffset offset within end container
+ * @property {string} [value.text] text content of the region, can be skipped
+ */

src/regions/TextRegion.js

@@ -0,0 +1,17 @@
+// stub file to keep TextRegion docs
+
+/**
+ * @example
+ * {
+ *   "value": {
+ *     "start": 2,
+ *     "end": 81,
+ *     "labels": ["Car"]
+ *   }
+ * }
+ * @typedef {Object} TextRegionResult
+ * @property {Object} value
+ * @property {string} value.start position of the start of the region in characters
+ * @property {string} value.end position of the end of the region in characters
+ * @property {string} [value.text] text content of the region, can be skipped
+ */

src/tags/object/HyperText.js

@@ -0,0 +1,35 @@
+// stub file to keep docs for HyperText object tag
+
+/**
+ * The HyperText tag displays hypertext markup for labeling. Use for labeling HTML-encoded text and webpages for NER and NLP projects.
+ *
+ * Use with the following data types: HTML
+ * @example
+ * <!--Labeling configuration to label HTML content -->
+ * <View>
+ *   <HyperText name="text-1" value="$text" />
+ *   <Labels name="parts" toName="text-1">
+ *     <Label value="Caption" />
+ *     <Label value="Article" />
+ *     <Label value="Author" />
+ *   </Labels>
+ * </View>
+ * @example
+ * <HyperText name="p1" value="<p>Some explanations <em>with style</em></p>" />
+ * @name HyperText
+ * @regions HyperTextRegion
+ * @meta_title Hypertext Tags for Hypertext Markup (HTML)
+ * @meta_description Label Studio Hypertext Tags customize Label Studio for hypertext markup (HTML) for machine learning and data science projects.
+ * @param {string} name                                   Name of the element
+ * @param {string} value                                  Value of the element
+ * @param {url|text} [valueType=text]                     Whether the text is stored directly in uploaded data or needs to be loaded from a URL
+ * @param {boolean} [inline=false]                        Whether to embed HTML directly in Label Studio or use an iframe
+ * @param {yes|no} [saveTextResult]                       Whether to store labeled text along with the results. By default, doesn't store text for `valueType=url`
+ * @param {none|base64|base64unicode} [encoding]          How to decode values from encoded strings
+ * @param {boolean} [selectionEnabled=true]               Enable or disable selection
+ * @param {boolean} [clickableLinks=false]                Whether to allow opening resources from links in the hypertext markup.
+ * @param {string} [highlightColor]                       Hex string with highlight color, if not provided uses the labels color
+ * @param {boolean} [showLabels]                          Whether or not to show labels next to the region; unset (by default) — use editor settings; true/false — override settings
+ * @param {symbol|word|sentence|paragraph} [granularity]  Control region selection granularity
+ */
+export const HyperTextModel = {};

src/tags/object/RichText/model.js

@@ -25,6 +25,8 @@ const WARNING_MESSAGES = {
 };
 
 /**
+ * WARNING: this is not a real doc, that's just a main reference; real docs are in their stub files: HyperText and Text
+ *
  * RichText tag shows text or HTML and allows labeling
  * @example
  * <RichText name="text-1" value="$text" granularity="symbol" highlightColor="#ff0000" />

src/tags/object/Text.js

@@ -0,0 +1,34 @@
+// stub file to keep docs for Text object tag
+
+/**
+ * The Text tag shows text that can be labeled. Use to display any type of text on the labeling interface.
+ * You can use `<Style>.htx-text{ white-space: pre-wrap; }</Style>` to preserve all spaces in the text, otherwise spaces are trimmed when displayed.
+ * Every space in the text sample is counted when calculating result offsets, for example for NER labeling tasks.
+ *
+ * Use with the following data types: text
+ * @example
+ * <!--Labeling configuration to label text for NER tasks with a word-level granularity -->
+ * <View>
+ *   <Text name="text-1" value="$text" granularity="word" highlightColor="#ff0000" />
+ *   <Labels name="ner" toName="text-1">
+ *     <Label value="Person" />
+ *     <Label value="Location" />
+ *   </Labels>
+ * </View>
+ * @example
+ * <Text name="p1">Some simple text with explanations</Text>
+ * @name Text
+ * @regions TextRegion
+ * @meta_title Text Tags for Text Objects
+ * @meta_description Customize Label Studio with the Text tag to annotate text for NLP and NER machine learning and data science projects.
+ * @param {string} name                                   Name of the element
+ * @param {string} value                                  Data field containing text or a UR
+ * @param {url|text} [valueType=text]                     Whether the text is stored directly in uploaded data or needs to be loaded from a URL
+ * @param {yes|no} [saveTextResult]                       Whether to store labeled text along with the results. By default, doesn't store text for `valueType=url`
+ * @param {none|base64|base64unicode} [encoding]          How to decode values from encoded strings
+ * @param {boolean} [selectionEnabled=true]               Enable or disable selection
+ * @param {string} [highlightColor]                       Hex string with highlight color, if not provided uses the labels color
+ * @param {boolean} [showLabels]                          Whether or not to show labels next to the region; unset (by default) — use editor settings; true/false — override settings
+ * @param {symbol|word|sentence|paragraph} [granularity]  Control region selection granularity
+ */
+export const TextModel = {};

src/tags/object/index.js

@@ -6,4 +6,8 @@ import { TimeSeriesModel } from "./TimeSeries";
 import { ParagraphsModel } from "./Paragraphs";
 import { VideoModel } from "./Video";
 
+// stub files to keep docs of these tags
+import "./HyperText";
+import "./Text";
+
 export { AudioModel, AudioPlusModel, ImageModel, ParagraphsModel, TimeSeriesModel, RichTextModel, VideoModel };