docs: Improve methods documentation (#2913)

packages/fiori/src/Page.js

@@ -43,7 +43,7 @@ const metadata = {
 		 * Disables vertical scrolling of page content.
 		 * If set to true, there will be no vertical scrolling at all.
 		 *
-		 * @type {Boolean}
+		 * @type {boolean}
 		 * @defaultvalue false
 		 * @public
 		 */
@@ -55,7 +55,7 @@ const metadata = {
 		 * Defines if the footer should float over the content.
 		 * <br><br>
 		 * <b>Note:</b> When set to true the footer floats over the content with a slight offset from the bottom, otherwise it is fixed at the very bottom of the page.
-		 * @type {Boolean}
+		 * @type {boolean}
 		 * @defaultvalue true
 		 * @public
 		 */
@@ -66,7 +66,7 @@ const metadata = {
 		/**
 		 * Defines the footer visibility.
 		 *
-		 * @type {Boolean}
+		 * @type {boolean}
 		 * @defaultvalue false
 		 * @public
 		 */

packages/fiori/src/ShellBar.js

@@ -745,7 +745,7 @@ class ShellBar extends UI5Element {
 
 	/**
 	 * Returns all items that will be placed in the right of the bar as icons / dom elements.
-	 * @param {Boolean} showOverflowButton Determines if overflow button should be visible (not overflowing)
+	 * @param {boolean} showOverflowButton Determines if overflow button should be visible (not overflowing)
 	 */
 	_getAllItems(showOverflowButton) {
 		let domOrder = -1;

packages/fiori/src/ShellBarItem.js

@@ -57,6 +57,7 @@ const metadata = {
 		 * Fired, when the item is pressed.
 		 *
 		 * @event sap.ui.webcomponents.fiori.ShellBarItem#item-click
+		 * @allowPreventDefault
 		 * @param {HTMLElement} targetRef dom ref of the clicked element
 		 * @public
 		 */

packages/fiori/src/SideNavigation.js

@@ -91,8 +91,10 @@ const metadata = {
 		 * @public
 		 */
 		"selection-change": {
-			item: {
-				type: HTMLElement,
+			detail: {
+				item: {
+					type: HTMLElement,
+				},
 			},
 		},
 	},

packages/main/src/AvatarGroup.js

@@ -220,7 +220,7 @@ class AvatarGroup extends UI5Element {
 	}
 
 	/**
-	 * Returns an array containing the ui5-avatar instances that are currently not displayed due to lack of space.
+	 * Returns an array containing the <code>ui5-avatar</code> instances that are currently not displayed due to lack of space.
 	 * @readonly
 	 * @type { Array }
 	 * @defaultValue []
@@ -231,7 +231,7 @@ class AvatarGroup extends UI5Element {
 	}
 
 	/**
-	 * Returns an array containing the <code>AvatarBackgroundColor</code> values that correspond to the avatars in the <code>items</code> array.
+	 * Returns an array containing the <code>AvatarBackgroundColor</code> values that correspond to the avatars in the <code>ui5-avatar-group</code>.
 	 * @readonly
 	 * @type { Array }
 	 * @defaultValue []

packages/main/src/ColorPalette.js

@@ -31,7 +31,7 @@ const metadata = {
 		/**
 		 * Defines whether the user can choose a custom color from a color picker
 		 * <b>Note:</b> In order to use this property you need to import the following module: <code>"@ui5/webcomponents/dist/features/ColorPaletteMoreColors.js"</code>
-		 * @type {Boolean}
+		 * @type {boolean}
 		 * @public
 		 * @since 1.0.0-rc.12
 		 */
@@ -74,7 +74,7 @@ const metadata = {
 		change: {
 			details: {
 				color: {
-					type: "String",
+					type: String,
 				},
 			},
 		 },

packages/main/src/DatePicker.js

@@ -82,7 +82,7 @@ const metadata = {
 		 * Defines whether the <code>ui5-date-picker</code> is required.
 		 *
 		 * @since 1.0.0-rc.9
-		 * @type {Boolean}
+		 * @type {boolean}
 		 * @defaultvalue false
 		 * @public
 		 */
@@ -555,8 +555,9 @@ class DatePicker extends DateComponentBase {
 	}
 
 	/**
-	 * Checks if a date is in range between minimum and maximum date.
-	 * @param {object} value
+	 * Checks if a date is between the minimum and maximum date.
+	 * @param {string} value
+	 * @returns {boolean}
 	 * @public
 	 */
 	isInValidRange(value = "") {
@@ -671,6 +672,7 @@ class DatePicker extends DateComponentBase {
 	 * Formats a Java Script date object into a string representing a locale date
 	 * according to the <code>formatPattern</code> property of the DatePicker instance
 	 * @param {object} oDate A Java Script date object to be formatted as string
+	 * @returns {string} The date as string
 	 * @public
 	 */
 	formatValue(oDate) {
@@ -688,6 +690,8 @@ class DatePicker extends DateComponentBase {
 	/**
 	 * Opens the picker.
 	 * @public
+	 * @async
+	 * @returns {Promise} Resolves when the picker is open
 	 */
 	async openPicker() {
 		this._isPickerOpen = true;
@@ -707,7 +711,7 @@ class DatePicker extends DateComponentBase {
 
 	/**
 	 * Checks if the picker is open.
-	 * @returns {Boolean} true if the picker is open, false otherwise
+	 * @returns {boolean} true if the picker is open, false otherwise
 	 * @public
 	 */
 	isOpen() {

packages/main/src/Dialog.js

@@ -183,6 +183,18 @@ class Dialog extends Popup {
 		return [PopupsCommonCss, dialogCSS];
 	}
 
+	/**
+	 * Opens the dialog
+	 *
+	 * @param {boolean} preventInitialFocus prevents applying the focus inside the popup
+	 * @async
+	 * @returns {Promise} Resolves when the dialog is open
+	 * @public
+	 */
+	async open(preventInitialFocus) {
+		await super.open(preventInitialFocus);
+	}
+
 	get isModal() { // Required by Popup.js
 		return true;
 	}

packages/main/src/Input.js

@@ -760,7 +760,7 @@ class Input extends UI5Element {
 
 	/**
 	 * Checks if the value state popover is open.
-	 * @returns {Boolean} true if the popover is open, false otherwise
+	 * @returns {boolean} true if the popover is open, false otherwise
 	 * @public
 	 */
 	isOpen() {

packages/main/src/Popover.js

@@ -291,6 +291,8 @@ class Popover extends Popup {
 	 * @param {HTMLElement} opener the element that the popover is opened by
 	 * @param {boolean} preventInitialFocus prevents applying the focus inside the popover
 	 * @public
+	 * @async
+	 * @returns {Promise} Resolved when the popover is open
 	 */
 	async openBy(opener, preventInitialFocus = false) {
 		if (!opener || this.opened) {

packages/main/src/Popup.js

@@ -115,10 +115,12 @@ const metadata = {
 		 * @public
 		 * @event sap.ui.webcomponents.main.Popup#before-close
 		 * @allowPreventDefault
-		 * @param {Boolean} escPressed Indicates that <code>ESC</code> key has triggered the event.
+		 * @param {boolean} escPressed Indicates that <code>ESC</code> key has triggered the event.
 		 */
 		"before-close": {
-			escPressed: { type: Boolean },
+			detail: {
+				escPressed: { type: Boolean },
+			},
 		},
 
 		/**
@@ -313,6 +315,8 @@ class Popup extends UI5Element {
 	 * Focuses the element denoted by <code>initialFocus</code>, if provided,
 	 * or the first focusable element otherwise.
 	 * @public
+	 * @async
+	 * @returns {Promise} Promise that resolves when the focus is applied
 	 */
 	async applyFocus() {
 		await this._waitForDomRef();
@@ -328,7 +332,7 @@ class Popup extends UI5Element {
 	}
 
 	/**
-	 * Override this method to provide custom logic for the popup's open/closed state. Maps to the "opened" property by default.
+	 * Tells if the component is open
 	 * @public
 	 * @returns {boolean}
 	 */
@@ -342,8 +346,7 @@ class Popup extends UI5Element {
 
 	/**
 	 * Shows the block layer (for modal popups only) and sets the correct z-index for the purpose of popup stacking
-	 * @param {boolean} preventInitialFocus prevents applying the focus inside the popup
-	 * @public
+	 * @protected
 	 */
 	async open(preventInitialFocus) {
 		const prevented = !this.fireEvent("before-open", {}, true, false);

packages/main/src/RangeSlider.js

@@ -496,7 +496,7 @@ class RangeSlider extends SliderBase {
 	/**
 	 * Flag if press action is made on the currently selected range of values
 	 *
-	 * @param {Boolean} isPressInCurrentRange Did the current press action occur in the current range (between the two handles)
+	 * @param {boolean} isPressInCurrentRange Did the current press action occur in the current range (between the two handles)
 	 * @private
 	 */
 	_setIsPressInCurrentRange(isPressInCurrentRange) {

packages/main/src/ResponsivePopover.js

@@ -89,7 +89,7 @@ class ResponsivePopover extends Popover {
 	static get styles() {
 		return [Popover.styles, ResponsivePopoverCss];
 	}
-	
+
 	get dialogClasses() {
 		return {
 			header: {
@@ -98,11 +98,11 @@ class ResponsivePopover extends Popover {
 			}
 		}
 	}
-	
+
 	static get template() {
 		return ResponsivePopoverTemplate;
 	}
-	
+
 	static get dependencies() {
 		return [
 			Button,
@@ -115,8 +115,10 @@ class ResponsivePopover extends Popover {
 	 * Opens popover on desktop and dialog on mobile.
 	 * @param {HTMLElement} opener the element that the popover is opened by
 	 * @public
+	 * @async
+	 * @returns {Promise} Resolves when the responsive popover is open
 	 */
-	open(opener) {
+	async open(opener) {
 		this.style.display = this._isPhone ? "contents" : "";
 
 		if (this.isOpen() || (this._dialog && this._dialog.isOpen())) {
@@ -129,10 +131,10 @@ class ResponsivePopover extends Popover {
 				this._minWidth = Math.max(POPOVER_MIN_WIDTH, opener.getBoundingClientRect().width);
 			}
 
-			this.openBy(opener);
+			await this.openBy(opener);
 		} else {
 			this.style.zIndex = getNextZIndex();
-			this._dialog.open();
+			await this._dialog.open();
 		}
 	}
 
@@ -156,6 +158,11 @@ class ResponsivePopover extends Popover {
 		this.open(opener);
 	}
 
+	/**
+	 * Tells if the responsive popover is open
+	 * @public
+	 * @returns {boolean}
+	 */
 	isOpen() {
 		return isPhone() ? this._dialog.isOpen() : super.isOpen();
 	}

packages/main/src/Select.js

@@ -150,7 +150,7 @@ const metadata = {
 		 * Defines whether the <code>ui5-select</code> is required.
 		 *
 		 * @since 1.0.0-rc.9
-		 * @type {Boolean}
+		 * @type {boolean}
 		 * @defaultvalue false
 		 * @public
 		 */

packages/main/src/StepInput.js

@@ -108,7 +108,7 @@ const metadata = {
 		/**
 		 * Defines whether the <code>ui5-step-input</code> is required.
 		 *
-		 * @type {Boolean}
+		 * @type {boolean}
 		 * @defaultvalue false
 		 * @public
 		 */
@@ -502,7 +502,7 @@ class StepInput extends UI5Element {
 	 * decrement buttons according to the value and min/max values (if set). Fires <code>change</code> event when requested
 	 *
 	 * @param {Float} modifier modifies the value of the component with the given modifier (positive or negative)
-	 * @param {Boolean} fireChangeEvent if <code>true</code>, fires <code>change</code> event when the value is changed
+	 * @param {boolean} fireChangeEvent if <code>true</code>, fires <code>change</code> event when the value is changed
 	 */
 	_modifyValue(modifier, fireChangeEvent) {
 		let value;

packages/main/src/TabContainer.js

@@ -203,8 +203,10 @@ const metadata = {
 		 * @public
 		 */
 		"tab-select": {
-			tab: { type: HTMLElement },
-			tabIndex: { type: Number },
+			detail: {
+				tab: { type: HTMLElement },
+				tabIndex: { type: Number },
+			},
 		},
 	},
 };

packages/main/src/TimePicker.js

@@ -131,7 +131,7 @@ class TimePicker extends TimePickerBase {
 	}
 
 	/**
-	 * Currently selected date represented as JavaScript Date instance
+	 * Currently selected time represented as JavaScript Date instance
 	 *
 	 * @readonly
 	 * @type { Date }

packages/main/src/TimePickerBase.js

@@ -295,7 +295,9 @@ class TimePickerBase extends UI5Element {
 
 	/**
 	 * Opens the picker.
+	 * @async
 	 * @public
+	 * @returns {Promise} Resolves when the picker is open
 	 */
 	async openPicker() {
 		this.tempValue = this.value && this.isValid(this.value) ? this.value : this.getFormat().format(new Date());
@@ -315,6 +317,7 @@ class TimePickerBase extends UI5Element {
 	/**
 	 * Checks if a value is valid against the current date format of the TimePicker
 	 * @public
+	 * @returns {boolean}
 	 */
 	isOpen() {
 		return !!this._isPickerOpen;
@@ -387,18 +390,20 @@ class TimePickerBase extends UI5Element {
 	 * according to the <code>formatPattern</code> property of the TimePicker instance
 	 * @param {object} oDate A Java Script date object to be formatted as string
 	 * @public
+	 * @returns {string}
 	 */
 	formatValue(oDate) {
 		return this.getFormat().format(oDate);
 	}
 
 	/**
-	 * Checks if a value is valid against the current format patternt of the TimePicker.
+	 * Checks if a value is valid against the current <code>formatPattern</code> value.
 	 *
 	 * <br><br>
 	 * <b>Note:</b> an empty string is considered as valid value.
 	 * @param {string} value The value to be tested against the current date format
 	 * @public
+	 * @returns {boolean}
 	 */
 	isValid(value) {
 		return value === "" || this.getFormat().parse(value);

packages/main/src/TreeItem.js

@@ -145,7 +145,6 @@ class TreeItem extends UI5Element {
 
 	/**
 	 * Call this method to manually switch the <code>expanded</code> state of a tree item.
-	 *
 	 * @public
 	 */
 	toggle() {

packages/main/src/WheelSlider.js

@@ -108,8 +108,10 @@ const metadata = {
 		 *  Fires when new value is selected.
 		 */
 		select: {
-			value: {
-				type: String,
+			detail: {
+				value: {
+					type: String,
+				},
 			},
 		},
 	},