docs: Adapt JSDocs for new CЕM and Remove Redundancies

docs/6-contributing/04-writing-samples.md

@@ -115,7 +115,7 @@ The above example includes only the `indeterminate`, `checked` properties in the
 
 
 ## Documentation
-The documentation for each component is automatically produced using the `custom-elements.json` file. Additionally, there is an `argTypes.ts` file located beside each `.stories.ts` file. It is generated during build time and contains extra properties that enhance the documentation beyond what is available in the `custom-elements.json` file. This file should not be edited directly, as it can only be modified by the `packages/playground/build-scripts-storybook/samples-prepare.js` script.
+The documentation for each component is automatically produced using the `custom-elements.json` file. Additionally, there is an `argTypes.ts` file located beside each `.stories.ts` file. It is generated during build time and contains extra properties that enhance the documentation beyond what is available in the `custom-elements.json` file. This file should not be edited directly, as it can only be modified by the `packages/playground/build-scripts-storybook/samples-prepare.ts` script.
 
 ### Docs page
 Every story has a `docs` page in the storybook's sidebar. Usually, this page is generated automatically by storybook but it can be customized by adding a `docs` property to the story parameters. 

packages/base/package-scripts.cjs

@@ -43,6 +43,8 @@ const scripts = {
 	generateTemplates: `mkdirp src/generated/templates && cross-env UI5_BASE=true UI5_TS=true node "${LIB}/hbs2ui5/index.js" -d test/elements -o src/generated/templates`,
 	generateAPI: {
 		default: "nps generateAPI.prepare generateAPI.preprocess generateAPI.jsdoc generateAPI.cleanup",
+		generateCEM: `cem analyze --config  "${LIB}/cem/custom-elements-manifest.config.mjs"`,
+		validateCEM: `node "${LIB}/cem/validate.js"`,
 		prepare: `copy-and-watch "dist/**/*.js" jsdoc-dist/`,
 		preprocess: `node "${preprocessJSDocScript}" jsdoc-dist/`,
 		jsdoc: `jsdoc -c "${LIB}/jsdoc/configTypescript.json"`,

packages/base/src/MediaRange.ts

@@ -11,8 +11,6 @@ DEAFULT_RANGE_SET.set("XL", [1440, Infinity]);
 /**
  * Enumeration containing the names and settings of predefined screen width media query range sets.
  *
- * @namespace
- * @name MediaRange.RANGESETS
  * @public
  */
  enum RANGESETS {
@@ -27,7 +25,6 @@ DEAFULT_RANGE_SET.set("XL", [1440, Infinity]);
 	 * <li><code>"XL"</code>: For screens greater than or equal to 1440 pixels.</li>
 	 * </ul>
 	 *
-	 * @name MediaRange.RANGESETS.RANGE_4STEPS
 	 * @public
 	 */
 	RANGE_4STEPS = "4Step",
@@ -49,10 +46,9 @@ DEAFULT_RANGE_SET.set("XL", [1440, Infinity]);
  * <li><code>"Large"</code>: For screens greater than or equal to 400 pixels.</li>
  * </ul>
  *
- * @param {string} name The name of the range set to be initialized.
+ * @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.
- * @param {Range} [range] The given range set.
- * @name MediaRange.initRangeSet
+ * @param range The given range set.
  */
 const initRangeSet = (name: string, range: Range) => {
 	mediaRanges.set(name, range);
@@ -64,13 +60,10 @@ const initRangeSet = (name: string, range: Range) => {
  * If the optional parameter <code>width</code> is given, the active range will be determined for that width,
  * otherwise it is determined for the current window size.
  *
- * @param {string} name The name of the range set. The range set must be initialized beforehand ({@link MediaRange.initRangeSet})
- * @param {number} [width] An optional width, based on which the range should be determined;
+ * @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.
- * @returns {string} The name of the current active interval of the range set.
- *
- * @name MediaRange.getCurrentRange
- * @function
+ * @returns The name of the current active interval of the range set.
  * @public
  */
 const getCurrentRange = (name: string, width = window.innerWidth): string => {
@@ -94,11 +87,7 @@ const getCurrentRange = (name: string, width = window.innerWidth): string => {
 
 /**
  * API for screen width changes.
- *
- * @namespace
- * @name MediaRange
  */
-
 const MediaRange = {
 	RANGESETS,
 	initRangeSet,

packages/base/src/StaticAreaItem.ts

@@ -10,9 +10,7 @@ const pureTagName = "ui5-static-area-item";
 const popupIntegrationAttr = "data-sap-ui-integration-popup-content";
 
 /**
- *
  * @class
- * @author SAP SE
  * @private
  */
 class StaticAreaItem extends HTMLElement {
@@ -26,7 +24,7 @@ class StaticAreaItem extends HTMLElement {
 	}
 
 	/**
-	 * @param {UI5Element} ownerElement the UI5Element instance that owns this static area item
+	 * @param ownerElement the UI5Element instance that owns this static area item
 	 */
 	setOwnerElement(ownerElement: UI5Element) {
 		this.ownerElement = ownerElement;
@@ -83,8 +81,8 @@ class StaticAreaItem extends HTMLElement {
 	}
 
 	/**
-	 * @protected
 	 * Returns reference to the DOM element where the current fragment is added.
+	 * @protected
 	 */
 	async getDomRef() {
 		this.updateAdditionalProperties();

packages/base/src/UI5Element.ts

@@ -80,12 +80,9 @@ function _invalidate(this: UI5Element, changeInfo: ChangeInfo) {
 }
 
 /**
+ * @class
  * Base class for all UI5 Web Components
  *
- * @class
- * @constructor
- * @author SAP SE
- * @alias sap.ui.webc.base.UI5Element
  * @extends HTMLElement
  * @public
  */
@@ -230,25 +227,25 @@ abstract class UI5Element extends HTMLElement {
 	 * Called every time before the component renders.
 	 * @public
 	 */
-	onBeforeRendering() {}
+	onBeforeRendering(): void {}
 
 	/**
 	 * Called every time after the component renders.
 	 * @public
 	 */
-	onAfterRendering() {}
+	onAfterRendering(): void {}
 
 	/**
 	 * Called on connectedCallback - added to the DOM.
 	 * @public
 	 */
-	onEnterDOM() {}
+	onEnterDOM(): void {}
 
 	/**
 	 * Called on disconnectedCallback - removed from the DOM.
 	 * @public
 	 */
-	onExitDOM() {}
+	onExitDOM(): void {}
 
 	/**
 	 * @private
@@ -438,28 +435,28 @@ abstract class UI5Element extends HTMLElement {
 	/**
 	 * Attach a callback that will be executed whenever the component is invalidated
 	 *
-	 * @param {InvalidationInfo} callback
+	 * @param callback
 	 * @public
 	 */
-	attachInvalidate(callback: (param: InvalidationInfo) => void) {
+	attachInvalidate(callback: (param: InvalidationInfo) => void): void {
 		this._invalidationEventProvider.attachEvent("invalidate", callback);
 	}
 
 	/**
 	 * Detach the callback that is executed whenever the component is invalidated
 	 *
-	 * @param {InvalidationInfo} callback
+	 * @param callback
 	 * @public
 	 */
-	detachInvalidate(callback: (param: InvalidationInfo) => void) {
+	detachInvalidate(callback: (param: InvalidationInfo) => void): void {
 		this._invalidationEventProvider.detachEvent("invalidate", callback);
 	}
 
 	/**
 	 * Callback that is executed whenever a monitored child changes its state
 	 *
-	 * @param {sting} slotName the slot in which a child was invalidated
-	 * @param { ChangeInfo } childChangeInfo the changeInfo object for the child in the given slot
+	 * @param slotName the slot in which a child was invalidated
+	 * @param childChangeInfo the changeInfo object for the child in the given slot
 	 * @private
 	 */
 	_onChildChange(slotName: string, childChangeInfo: ChangeInfo) {
@@ -576,24 +573,22 @@ abstract class UI5Element extends HTMLElement {
 	 * Returns a singleton event listener for the "change" event of a child in a given slot
 	 *
 	 * @param slotName the name of the slot, where the child is
-	 * @returns {ChildChangeListener}
 	 * @private
 	 */
-	_getChildChangeListener(slotName: string) {
+	_getChildChangeListener(slotName: string): ChildChangeListener {
 		if (!this._childChangeListeners.has(slotName)) {
 			this._childChangeListeners.set(slotName, this._onChildChange.bind(this, slotName));
 		}
-		return this._childChangeListeners.get(slotName);
+		return this._childChangeListeners.get(slotName)!;
 	}
 
 	/**
 	 * Returns a singleton slotchange event listener that invalidates the component due to changes in the given slot
 	 *
 	 * @param slotName the name of the slot, where the slot element (whose slotchange event we're listening to) is
-	 * @returns {SlotChangeListener}
 	 * @private
 	 */
-	_getSlotChangeListener(slotName: string) {
+	_getSlotChangeListener(slotName: string): SlotChangeListener {
 		if (!this._slotChangeListeners.has(slotName)) {
 			this._slotChangeListeners.set(slotName, this._onSlotChange.bind(this, slotName));
 		}
@@ -658,7 +653,7 @@ abstract class UI5Element extends HTMLElement {
 	 *
 	 * @public
 	 */
-	onInvalidation(changeInfo: ChangeInfo) {} // eslint-disable-line
+	onInvalidation(changeInfo: ChangeInfo): void {} // eslint-disable-line
 
 	/**
 	 * Do not call this method directly, only intended to be called by js
@@ -746,7 +741,7 @@ abstract class UI5Element extends HTMLElement {
 	 *
 	 * @public
 	 */
-	getDomRef() {
+	getDomRef(): HTMLElement | undefined {
 		// If a component set _getRealDomRef to its children, use the return value of this function
 		if (typeof this._getRealDomRef === "function") {
 			return this._getRealDomRef();
@@ -769,7 +764,7 @@ abstract class UI5Element extends HTMLElement {
 	 * This is the element that will receive the focus by default.
 	 * @public
 	 */
-	getFocusDomRef() {
+	getFocusDomRef(): HTMLElement | undefined {
 		const domRef = this.getDomRef();
 		if (domRef) {
 			const focusRef = domRef.querySelector("[data-sap-focus-ref]") as HTMLElement;
@@ -782,17 +777,17 @@ abstract class UI5Element extends HTMLElement {
 	 * This is the element that will receive the focus by default.
 	 * @public
 	 */
-	async getFocusDomRefAsync() {
+	async getFocusDomRefAsync(): Promise<HTMLElement | undefined> {
 		await this._waitForDomRef();
 		return this.getFocusDomRef();
 	}
 
 	/**
 	 * Set the focus to the element, returned by "getFocusDomRef()" (marked by "data-sap-focus-ref")
-	 * @param {FocusOptions} focusOptions additional options for the focus
+	 * @param focusOptions additional options for the focus
 	 * @public
 	 */
-	async focus(focusOptions?: FocusOptions) {
+	async focus(focusOptions?: FocusOptions): Promise<void> {
 		await this._waitForDomRef();
 
 		const focusDomRef = this.getFocusDomRef();
@@ -809,9 +804,9 @@ abstract class UI5Element extends HTMLElement {
 	 * @param data - additional data for the event
 	 * @param cancelable - true, if the user can call preventDefault on the event object
 	 * @param bubbles - true, if the event bubbles
-	 * @returns {boolean} false, if the event was cancelled (preventDefault called), true otherwise
+	 * @returns false, if the event was cancelled (preventDefault called), true otherwise
 	 */
-	fireEvent<T>(name: string, data?: T, cancelable = false, bubbles = true) {
+	fireEvent<T>(name: string, data?: T, cancelable = false, bubbles = true): boolean {
 		const eventResult = this._fireEvent(name, data, cancelable, bubbles);
 		const camelCaseEventName = kebabToCamelCase(name);
 
@@ -856,27 +851,27 @@ abstract class UI5Element extends HTMLElement {
 	 * Useful when there are transitive slots in nested component scenarios and you don't want to get a list of the slots, but rather of their content.
 	 * @public
 	 */
-	getSlottedNodes<T = Node>(slotName: string) {
+	getSlottedNodes<T = Node>(slotName: string): Array<T> {
 		return getSlottedNodesList((this as unknown as Record<string, Array<SlotValue>>)[slotName]) as Array<T>;
 	}
 
 	/**
 	 * Attach a callback that will be executed whenever the component's state is finalized
 	 *
-	 * @param {} callback
+	 * @param callback
 	 * @public
 	 */
-	attachComponentStateFinalized(callback: () => void) {
+	attachComponentStateFinalized(callback: () => void): void {
 		this._componentStateFinalizedEventProvider.attachEvent("componentStateFinalized", callback);
 	}
 
 	/**
 	 * Detach the callback that is executed whenever the component's state is finalized
 	 *
-	 * @param {} callback
+	 * @param callback
 	 * @public
 	 */
-	detachComponentStateFinalized(callback: () => void) {
+	detachComponentStateFinalized(callback: () => void): void {
 		this._componentStateFinalizedEventProvider.detachEvent("componentStateFinalized", callback);
 	}
 
@@ -885,19 +880,19 @@ abstract class UI5Element extends HTMLElement {
 	 * Returns: "rtl", "ltr" or undefined
 	 *
 	 * @public
-	 * @returns {String|undefined}
+	 * @default undefined
 	 */
-	get effectiveDir() {
+	get effectiveDir(): string | undefined {
 		markAsRtlAware(this.constructor as typeof UI5Element); // if a UI5 Element calls this method, it's considered to be rtl-aware
 		return getEffectiveDir(this);
 	}
 
 	/**
 	 * Used to duck-type UI5 elements without using instanceof
-	 * @returns {boolean}
 	 * @public
+	 * @default true
 	 */
-	get isUI5Element() {
+	get isUI5Element(): boolean {
 		return true;
 	}
 
@@ -930,7 +925,7 @@ abstract class UI5Element extends HTMLElement {
 	/**
 	 * @public
 	 */
-	getStaticAreaItemDomRef() {
+	getStaticAreaItemDomRef(): Promise<ShadowRoot | null> {
 		if (!(this.constructor as typeof UI5Element)._needsStaticArea()) {
 			throw new Error("This component does not use the static area");
 		}
@@ -1093,7 +1088,7 @@ abstract class UI5Element extends HTMLElement {
 	 *
 	 * @public
 	 */
-	static getUniqueDependencies(this: typeof UI5Element) {
+	static getUniqueDependencies(this: typeof UI5Element): Array<typeof UI5Element> {
 		if (!uniqueDependenciesCache.has(this)) {
 			const filtered = this.dependencies.filter((dep, index, deps) => deps.indexOf(dep) === index);
 			uniqueDependenciesCache.set(this, filtered);
@@ -1104,8 +1099,6 @@ abstract class UI5Element extends HTMLElement {
 
 	/**
 	 * Returns a promise that resolves whenever all dependencies for this UI5 Web Component have resolved
-	 *
-	 * @returns {Promise}
 	 */
 	static whenDependenciesDefined(): Promise<Array<typeof UI5Element>> {
 		return Promise.all(this.getUniqueDependencies().map(dep => dep.define()));
@@ -1115,18 +1108,16 @@ abstract class UI5Element extends HTMLElement {
 	 * Hook that will be called upon custom element definition
 	 *
 	 * @protected
-	 * @returns {Promise<void>}
 	 */
-	static async onDefine() {
+	static async onDefine(): Promise<void> {
 		return Promise.resolve();
 	}
 
 	/**
 	 * Registers a UI5 Web Component in the browser window object
 	 * @public
-	 * @returns {Promise<UI5Element>}
 	 */
-	static async define() {
+	static async define(): Promise<typeof UI5Element> {
 		await boot();
 
 		await Promise.all([
@@ -1154,9 +1145,8 @@ abstract class UI5Element extends HTMLElement {
 	 * Returns an instance of UI5ElementMetadata.js representing this UI5 Web Component's full metadata (its and its parents')
 	 * Note: not to be confused with the "get metadata()" method, which returns an object for this class's metadata only
 	 * @public
-	 * @returns {UI5ElementMetadata}
 	 */
-	static getMetadata() {
+	static getMetadata(): UI5ElementMetadata {
 		if (this.hasOwnProperty("_metadata")) { // eslint-disable-line
 			return this._metadata;
 		}
@@ -1176,7 +1166,6 @@ abstract class UI5Element extends HTMLElement {
 
 /**
  * Always use duck-typing to cover all runtimes on the page.
- * @returns {boolean}
  */
 const instanceOfUI5Element = (object: any): object is UI5Element => {
 	return "isUI5Element" in object;