From 69312108f37e2f58d95304eaa7d482307fdaaf31 Mon Sep 17 00:00:00 2001
From: Nayden Naydenov <31909318+nnaydenow@users.noreply.github.com>
Date: Fri, 1 Mar 2024 20:48:47 +0200
Subject: [PATCH] chore: migrate to md jsdoc in base (#8379)

---
 packages/base/src/Boot.ts                     |  2 +-
 packages/base/src/CSP.ts                      | 15 +++++----
 packages/base/src/IgnoreCustomElements.ts     |  8 ++---
 packages/base/src/MediaRange.ts               | 32 +++++++++----------
 packages/base/src/UI5ElementMetadata.ts       |  4 +--
 packages/base/src/asset-registries/i18n.ts    |  4 +--
 .../util/IconCollectionsByTheme.ts            |  2 +-
 packages/base/src/config/Icons.ts             | 14 ++++----
 packages/base/src/config/Language.ts          |  2 +-
 packages/base/src/config/Theme.ts             |  2 +-
 packages/base/src/config/ThemeRoot.ts         |  6 ++--
 packages/base/src/config/Timezone.ts          |  2 +-
 packages/base/src/locale/applyDirection.ts    |  5 +--
 packages/base/src/types/DOMReference.ts       |  2 +-
 packages/base/src/util/createLinkInHead.ts    |  2 +-
 packages/base/src/util/createStyleInHead.ts   |  2 +-
 16 files changed, 52 insertions(+), 52 deletions(-)

diff --git a/packages/base/src/Boot.ts b/packages/base/src/Boot.ts
index 49060595977f..500a01f1fcaf 100644
--- a/packages/base/src/Boot.ts
+++ b/packages/base/src/Boot.ts
@@ -21,7 +21,7 @@ const isBooted = (): boolean => {
 
 /**
  * Attaches a callback that will be executed after boot finishes.
- * <b>Note:</b> If the framework already booted, the callback will be immediately executed.
+ * **Note:** If the framework already booted, the callback will be immediately executed.
  * @public
  * @param { Function } listener
  */
diff --git a/packages/base/src/CSP.ts b/packages/base/src/CSP.ts
index 35c3a069e0ba..a0bd276da47c 100644
--- a/packages/base/src/CSP.ts
+++ b/packages/base/src/CSP.ts
@@ -25,9 +25,11 @@ const getUrl = (packageName: string, path: string) => {
 };
 
 /**
- * Call this function to enable or disable the usage of <link> tags instead of <style> tags to achieve CSP compliance
- * Example: "setUseLinks(true)" will unconditionally use <link> tags for all browsers;
- * Example: "setUseLinks(!document.adoptedStyleSheets) will only enable the usage of <link> tags for browsers that do not support constructable stylesheets.
+ * Call this function to enable or disable the usage of `<link>` tags instead of `<style>` tags to achieve CSP compliance
+ *
+ * Example: "setUseLinks(true)" will unconditionally use `<link>` tags for all browsers.
+ *
+ * Example: "setUseLinks(!document.adoptedStyleSheets) will only enable the usage of `<link>` tags for browsers that do not support constructable stylesheets.
  *
  * @public
  * @param use whether links will be used
@@ -37,9 +39,10 @@ const setUseLinks = (use: boolean) => {
 };
 
 /**
- * Call this function to enable or disable the preloading of <link> tags.
- * Note: only taken into account when <link> tags are being used.
- * Note: links are being preloaded by default, so call "setPreloadLinks(false)" to opt out of this.
+ * Call this function to enable or disable the preloading of `<link>` tags.
+ *
+ * **Note:** only taken into account when `<link>` tags are being used.
+ * **Note:** links are being preloaded by default, so call "setPreloadLinks(false)" to opt out of this.
  *
  * @public
  * @param preload
diff --git a/packages/base/src/IgnoreCustomElements.ts b/packages/base/src/IgnoreCustomElements.ts
index 817ac134de33..0ee25b7e705b 100644
--- a/packages/base/src/IgnoreCustomElements.ts
+++ b/packages/base/src/IgnoreCustomElements.ts
@@ -5,16 +5,14 @@ const tagPrefixes: Array<string> = [];
 
 /**
  * Ignores all custom HTML elements with a given tag prefix to improve the rendering performance of the UI5 Web Components.
- * <br>
  *
- * <b>When used:</b> the UI5 Web Components framework treats all custom HTML elements,
+ * **When used:** the UI5 Web Components framework treats all custom HTML elements,
  * starting with the given prefix as if they are standard HTML elements, such as: `div`, `span`, etc, without additional processing.
- * <br>
  *
- * <b>When not used:</b> the framework waits for the slotted children to be defined and registered first,
+ * **When not used:** the framework waits for the slotted children to be defined and registered first,
  * because the state or visual appearance of the parent may rely on the slotted elements/children.
  *
- * <b>Note:</b> We recommend using `ignoreCustomElements` when slotting custom HTML elements (with only semantic purpose)
+ * **Note:** We recommend using `ignoreCustomElements` when slotting custom HTML elements (with only semantic purpose)
  * inside UI5 Web Components, to improve the time to render.
  *
  * @public
diff --git a/packages/base/src/MediaRange.ts b/packages/base/src/MediaRange.ts
index d81f2aa58eb8..3e6be8116ab7 100644
--- a/packages/base/src/MediaRange.ts
+++ b/packages/base/src/MediaRange.ts
@@ -18,12 +18,12 @@ DEAFULT_RANGE_SET.set("XL", [1440, Infinity]);
 	 * A 4-step range set (S-M-L-XL).
 	 *
 	 * The ranges of this set are:
-	 * <ul>
-	 * <li><code>"S"</code>: For screens smaller than 600 pixels.</li>
-	 * <li><code>"M"</code>: For screens greater than or equal to 600 pixels and smaller than 1024 pixels.</li>
-	 * <li><code>"L"</code>: For screens greater than or equal to 1024 pixels and smaller than 1440 pixels.</li>
-	 * <li><code>"XL"</code>: For screens greater than or equal to 1440 pixels.</li>
-	 * </ul>
+	 *
+	 * - `"S"`: For screens smaller than 600 pixels.
+	 * - `"M"`: For screens greater than or equal to 600 pixels and smaller than 1024 pixels.
+	 * - `"L"`: For screens greater than or equal to 1024 pixels and smaller than 1440 pixels.
+	 * - `"XL"`: For screens greater than or equal to 1440 pixels.
+	 *
 	 *
 	 * @public
 	 */
@@ -33,18 +33,18 @@ DEAFULT_RANGE_SET.set("XL", [1440, Infinity]);
 /**
  * Initializes a screen width media query range set.
  *
- * This initialization step makes the range set ready to be used for one of the other functions in namespace <code>MediaRange</code>.
+ * This initialization step makes the range set ready to be used for one of the other functions in namespace `MediaRange`.
  *
  * A range set can be defined as shown in the following example:
- * <pre>
+ * ```
  * MediaRange.initRangeSet("MyRangeSet", [200, 400], ["Small", "Medium", "Large"]);
- * </pre>
+ * ```
  * This example defines the following named ranges:
- * <ul>
- * <li><code>"Small"</code>: For screens smaller than 200 pixels.</li>
- * <li><code>"Medium"</code>: For screens greater than or equal to 200 pixels and smaller than 400 pixels.</li>
- * <li><code>"Large"</code>: For screens greater than or equal to 400 pixels.</li>
- * </ul>
+ *
+ * - `"Small"`: For screens smaller than 200 pixels.
+ * - `"Medium"`: For screens greater than or equal to 200 pixels and smaller than 400 pixels.
+ * - `"Large"`: For screens greater than or equal to 400 pixels.
+ *
  *
  * @param name The name of the range set to be initialized.
  * The name must be a valid id and consist only of letters and numeric digits.
@@ -57,12 +57,12 @@ const initRangeSet = (name: string, range: Range) => {
 /**
  * Returns information about the current active range of the range set with the given name.
  *
- * If the optional parameter <code>width</code> is given, the active range will be determined for that width,
+ * If the optional parameter `width` is given, the active range will be determined for that width,
  * otherwise it is determined for the current window size.
  *
  * @param name The name of the range set. The range set must be initialized beforehand ({@link MediaRange.initRangeSet})
  * @param [width] An optional width, based on which the range should be determined;
- * If <code>width</code> is not provided, the window size will be used.
+ * If `width` is not provided, the window size will be used.
  * @returns The name of the current active interval of the range set.
  * @public
  */
diff --git a/packages/base/src/UI5ElementMetadata.ts b/packages/base/src/UI5ElementMetadata.ts
index 82d1dc61aa77..896db29d3625 100644
--- a/packages/base/src/UI5ElementMetadata.ts
+++ b/packages/base/src/UI5ElementMetadata.ts
@@ -113,7 +113,7 @@ class UI5ElementMetadata {
 	/**
 	 * Validates the property's value and returns it if correct
 	 * or returns the default value if not.
-	 * <b>Note:</b> Only intended for use by UI5Element.js
+	 * **Note:** Only intended for use by UI5Element.js
 	 * @public
 	 */
 	static validatePropertyValue(value: PropertyValue, propData: Property): PropertyValue {
@@ -127,7 +127,7 @@ class UI5ElementMetadata {
 	/**
 	 * Validates the slot's value and returns it if correct
 	 * or throws an exception if not.
-	 * <b>Note:</b> Only intended for use by UI5Element.js
+	 * **Note:** Only intended for use by UI5Element.js
 	 * @public
 	 */
 	static validateSlotValue(value: Node, slotData: Slot): Node {
diff --git a/packages/base/src/asset-registries/i18n.ts b/packages/base/src/asset-registries/i18n.ts
index f93adf1e232f..b1a873f02e02 100644
--- a/packages/base/src/asset-registries/i18n.ts
+++ b/packages/base/src/asset-registries/i18n.ts
@@ -71,8 +71,8 @@ const useFallbackBundle = (packageName: string, localeId: string) => {
  * This method preforms the asynchronous task of fetching the actual text resources. It will fetch
  * each text resource over the network once (even for multiple calls to the same method).
  * It should be fully finished before the i18nBundle class is created in the webcomponents.
- * This method uses the bundle URLs that are populated by the <code>registerI18nBundle</code> method.
- * To simplify the usage, the synchronization of both methods happens internally for the same <code>bundleId</code>
+ * This method uses the bundle URLs that are populated by the `registerI18nBundle` method.
+ * To simplify the usage, the synchronization of both methods happens internally for the same `bundleId`
  * @param {packageName} packageName the NPM package name
  * @public
  */
diff --git a/packages/base/src/asset-registries/util/IconCollectionsByTheme.ts b/packages/base/src/asset-registries/util/IconCollectionsByTheme.ts
index 970f90a56046..296341803643 100644
--- a/packages/base/src/asset-registries/util/IconCollectionsByTheme.ts
+++ b/packages/base/src/asset-registries/util/IconCollectionsByTheme.ts
@@ -27,7 +27,7 @@ iconCollections.set("business-suite", {
 
 /**
  * Registers collection version per theme.
- * </b>For exmaple:</b> registerIconCollectionForTheme("my-custom-icons", {"sap_horizon": "my-custom-icons-v5"})
+ * **For exmaple:** registerIconCollectionForTheme("my-custom-icons", {"sap_horizon": "my-custom-icons-v5"})
  * @param { string } collectionName
  * @param { ThemeToCollectionMap } themeCollectionMap
  */
diff --git a/packages/base/src/config/Icons.ts b/packages/base/src/config/Icons.ts
index 9335d8d7e81c..ba29f408cfad 100644
--- a/packages/base/src/config/Icons.ts
+++ b/packages/base/src/config/Icons.ts
@@ -10,22 +10,22 @@ type IconCollection = string;
  * and to display icons from other collections, you have to specify the icon collection in addition to the icon name, for example: "tnt/actor", "business-suite/1x2-grid-layout", etc.
  * This method allows setting another (built-in or custom) icon collection as default per theme.
  *
- * <b>Usage</b>
- * <b>For example</b>, to make "SAP-icons version 5.x" the default icon collection in "sap_fiori_3":
+ * **Usage**
+ * **For example**, to make "SAP-icons version 5.x" the default icon collection in "sap_fiori_3":
  *
- * <pre>
+ * ```
  * setDefaultIconCollection("sap_fiori_3", "SAP-icons-v5");
  *
  * <ui5-icon name="home"></ui5-icon>
- * </pre>
+ * ```
  *
- * <b>For example</b>, to make a custom icon collection (with name "my-custom-collection") the default icon collection in "sap_fiori_3":
+ * **For example**, to make a custom icon collection (with name "my-custom-collection") the default icon collection in "sap_fiori_3":
  *
- * <pre>
+ * ```
  * setDefaultIconCollection("sap_fiori_3", "my-custom-collection");
  *
  * <ui5-icon name="custom-icon-name"></ui5-icon>
- * </pre>
+ * ```
  *
  * @public
  * @param { string } theme
diff --git a/packages/base/src/config/Language.ts b/packages/base/src/config/Language.ts
index ab06cb771953..ae1b89f3a5e7 100644
--- a/packages/base/src/config/Language.ts
+++ b/packages/base/src/config/Language.ts
@@ -58,7 +58,7 @@ const getDefaultLanguage = (): string => {
 /**
  * Defines if the default language, that is inlined, should be
  * fetched over the network instead of using the inlined one.
- * <b>Note:</b> By default the language will not be fetched.
+ * **Note:** By default the language will not be fetched.
  *
  * @public
  * @param {boolean} fetchDefaultLang
diff --git a/packages/base/src/config/Theme.ts b/packages/base/src/config/Theme.ts
index 5f837090ab42..a3e3d8cc0467 100644
--- a/packages/base/src/config/Theme.ts
+++ b/packages/base/src/config/Theme.ts
@@ -65,7 +65,7 @@ const isTheme = (theme: string) => {
 
 /**
  * Returns if the currently set theme is part of legacy theme families ("sap_belize" or "sap_fiori_3").
- * <b>Note</b>: in addition, the method checks the base theme of a custom theme, built via the ThemeDesigner.
+ * **Note**: in addition, the method checks the base theme of a custom theme, built via the ThemeDesigner.
  *
  * @private
  * @returns { boolean }
diff --git a/packages/base/src/config/ThemeRoot.ts b/packages/base/src/config/ThemeRoot.ts
index f779e1d85702..e11ad44af03e 100644
--- a/packages/base/src/config/ThemeRoot.ts
+++ b/packages/base/src/config/ThemeRoot.ts
@@ -24,12 +24,10 @@ const getThemeRoot = (): string | undefined => {
  * Sets theme root for the current theme.
  * When set, the framework will validate the theme root and fetch the theme styles (CSS variables) from this location.
  *
- * <b>Note:</b> The feature is specific to custom themes, created with the `UI Theme Designer`.
+ * **Note:** The feature is specific to custom themes, created with the `UI Theme Designer`.
  * The provided theme root is used only as a base to construct the actual location of the theme styles: `{themeRoot}/.../css_variables.css`.
  *
- * <br/>
- *
- * <b>Note:</b> Certain security restrictions will apply before fetching the theme assets.
+ * **Note:** Certain security restrictions will apply before fetching the theme assets.
  * Absolute URLs to a different origin than the current page will result in using the current page as an origin.
  * To allow specific origins, use &lt;meta name="sap-allowedThemeOrigins" content="https://my-example-host.com/"&gt; tag inside the &lt;head&gt; of the page.
  *
diff --git a/packages/base/src/config/Timezone.ts b/packages/base/src/config/Timezone.ts
index d395211c068c..11cf35987897 100644
--- a/packages/base/src/config/Timezone.ts
+++ b/packages/base/src/config/Timezone.ts
@@ -17,7 +17,7 @@ const getTimezone = (): string | undefined => {
 
 /**
  * Sets the IANA timezone ID.
- * <b>For example:</b> "America/New_York", "Europe/London", "Australia/Sydney", "Asia/Bishkek", etc.
+ * **For example:** "America/New_York", "Europe/London", "Australia/Sydney", "Asia/Bishkek", etc.
  *>
  * @param {string} timezone
  * @private
diff --git a/packages/base/src/locale/applyDirection.ts b/packages/base/src/locale/applyDirection.ts
index 3d1ffb315526..b2ac5a59eb29 100644
--- a/packages/base/src/locale/applyDirection.ts
+++ b/packages/base/src/locale/applyDirection.ts
@@ -4,8 +4,9 @@ import { fireDirectionChange } from "./directionChange.js";
 /**
  * Re-renders all RTL-aware UI5 Elements.
  *
- * <b>Note:</b> Call this method whenever you change the "dir" property anywhere in your HTML page.
- * <b>Example:</b> <code>document.body.dir = "rtl"; applyDirection();</code>
+ * **Note:** Call this method whenever you change the "dir" property anywhere in your HTML page.
+ *
+ * **Example:** `document.body.dir = "rtl"; applyDirection();`
  * @public
  * @returns {Promise<void>}
  */
diff --git a/packages/base/src/types/DOMReference.ts b/packages/base/src/types/DOMReference.ts
index 85756fabf2b8..cfc1af8bcf7c 100644
--- a/packages/base/src/types/DOMReference.ts
+++ b/packages/base/src/types/DOMReference.ts
@@ -3,7 +3,7 @@ import DataType from "./DataType.js";
 /**
  * @class
  * DOM Element reference or ID.
- * <b>Note:</b> If an ID is passed, it is expected to be part of the same <code>document</code> element as the consuming component.
+ * **Note:** If an ID is passed, it is expected to be part of the same `document` element as the consuming component.
  *
  * @public
  */
diff --git a/packages/base/src/util/createLinkInHead.ts b/packages/base/src/util/createLinkInHead.ts
index 22d33eb338e0..882ab7ffa5fe 100644
--- a/packages/base/src/util/createLinkInHead.ts
+++ b/packages/base/src/util/createLinkInHead.ts
@@ -1,5 +1,5 @@
 /**
- * Creates a <link> tag in the <head> tag
+ * Creates a `<link>` tag in the `<head>` tag
  * @param href - the CSS
  * @param attributes - optional attributes to add to the tag
  */
diff --git a/packages/base/src/util/createStyleInHead.ts b/packages/base/src/util/createStyleInHead.ts
index acfd33231be7..ce89b477fea0 100644
--- a/packages/base/src/util/createStyleInHead.ts
+++ b/packages/base/src/util/createStyleInHead.ts
@@ -1,5 +1,5 @@
 /**
- * Creates a <style> tag in the <head> tag
+ * Creates a `<style>` tag in the `<head>` tag
  * @param cssText - the CSS
  * @param attributes - optional attributes to add to the tag
  * @returns {HTMLElement}