docs: rewrite JSDoc for custom-elements-manifest/analyzer (#7778)

* docs: new cem for Topic-RD components JSDoc changes related to using the new custom-elements-manifest for Rodopi-owned components. Issue: #7610 * docs: remove types from enums * docs: rewrite JSDoc for custom-elements-manifest/analyzer Related to: #7610 * docs: rewrite JSDoc for custom-elements-manifest/analyzer Related to: #7610 * docs: rewrite JSDoc for custom-elements-manifest/analyzer Related to: #7610 * docs: rewrite JSDoc for custom-elements-manifest/analyzer Related to: #7610 * docs: rewrite JSDoc for custom-elements-manifest/analyzer Related to: #7610 * chore: fulfill * docs: rewrite JSDoc for custom-elements-manifest/analyzer Related to: #7610 --------- Co-authored-by: Nayden Naydenov <[email protected]>
SAP · Nov 30, 2023 · c3a9185 · c3a9185
1 parent 7db5b50
commit c3a9185
Show file tree

Hide file tree

Showing 43 changed files with 290 additions and 954 deletions.
diff --git a/packages/fiori/src/Interfaces.ts b/packages/fiori/src/Interfaces.ts
@@ -36,23 +36,13 @@ interface IMediaGalleryItem {
 	focused: boolean,
 }
 
-/**
- * Interface for components that may be slotted as an action inside <code>ui5-li-notification</code> and <code>ui5-li-notification-group</code>
- *
- * @name sap.ui.webc.fiori.INotificationAction
- * @interface
- * @public
- */
-const INotificationAction = "sap.ui.webc.fiori.INotificationAction";
-
 /**
  * Interface for components that may be slotted inside a notification list
  *
- * @name sap.ui.webc.fiori.INotificationListItem
- * @interface
  * @public
  */
-const INotificationListItem = "sap.ui.webc.fiori.INotificationListItem";
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+interface INotificationListItem extends HTMLElement { }
 
 /**
  * Interface for components that may be slotted inside <code>ui5-product-switch</code> as items
@@ -69,22 +59,13 @@ interface IProductSwitchItem {
 }
 
 /**
- * Interface for components that may be slotted inside <code>ui5-side-navigation</code> as items
+ * Interface for components that may be slotted inside <code>ui5-shellbar</code> as items
  *
- * @name sap.ui.webc.fiori.ISideNavigationItem
+ * @name sap.ui.webc.fiori.IShellBarItem
  * @interface
  * @public
  */
-const ISideNavigationItem = "sap.ui.webc.fiori.ISideNavigationItem";
-
-/**
- * Interface for components that may be slotted inside <code>ui5-side-navigation-item</code> as sub-items
- *
- * @name sap.ui.webc.fiori.ISideNavigationSubItem
- * @interface
- * @public
- */
-const ISideNavigationSubItem = "sap.ui.webc.fiori.ISideNavigationSubItem";
+const IShellBarItem = "sap.ui.webc.fiori.IShellBarItem";
 
 /**
  * Interface for components that may be slotted inside <code>ui5-view-settings-dialog</code> as sort items
@@ -107,11 +88,10 @@ const ITimelineItem = "sap.ui.webc.fiori.ITimelineItem";
 /**
  * Interface for components that may be slotted inside <code>ui5-upload-collection</code> as items
  *
- * @name sap.ui.webc.fiori.IUploadCollectionItem
- * @interface
  * @public
  */
-const IUploadCollectionItem = "sap.ui.webc.fiori.IUploadCollectionItem";
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+interface IUploadCollectionItem extends HTMLElement { }
 
 /**
  * Interface for components that may be slotted inside <code>ui5-wizard</code> as wizard steps
@@ -127,11 +107,9 @@ export {
 	IFilterItem,
 	IFilterItemOption,
 	IMediaGalleryItem,
-	INotificationAction,
 	INotificationListItem,
 	IProductSwitchItem,
-	ISideNavigationItem,
-	ISideNavigationSubItem,
+	IShellBarItem,
 	ISortItem,
 	ITimelineItem,
 	IUploadCollectionItem,

diff --git a/packages/fiori/src/NotificationAction.ts b/packages/fiori/src/NotificationAction.ts
@@ -15,20 +15,14 @@ type NotificationActionClickEventDetail = {
  * used in the <code>ui5-li-notification</code> and the <code>ui5-li-notification-group</code> items.
  *
  * @constructor
- * @author SAP SE
- * @alias sap.ui.webc.fiori.NotificationAction
- * @extends sap.ui.webc.base.UI5Element
- * @abstract
- * @tagname ui5-notification-action
- * @implements sap.ui.webc.fiori.INotificationAction
+ * @extends UI5Element
  * @public
  */
 @customElement("ui5-notification-action")
 
 /**
  * Fired, when the action is pressed.
  *
- * @event sap.ui.webc.fiori.NotificationAction#click
  * @param {HTMLElement} targetRef DOM ref of the clicked element
  * @public
  */
@@ -41,10 +35,8 @@ class NotificationAction extends UI5Element {
 	/**
 	 * Defines the text of the <code>ui5-notification-action</code>.
 	 *
-	 * @type {string}
-	 * @defaultvalue ""
+	 * @default ""
 	 * @public
-	 * @name sap.ui.webc.fiori.NotificationAction.prototype.text
 	 */
 	@property()
 	text!: string;
@@ -54,21 +46,17 @@ class NotificationAction extends UI5Element {
 	 * <br><br>
 	 * <b>Note:</b> a disabled action can't be pressed or focused, and it is not in the tab chain.
 	 *
-	 * @type {boolean}
-	 * @defaultvalue false
+	 * @default false
 	 * @public
-	 * @name sap.ui.webc.fiori.NotificationAction.prototype.disabled
 	 */
 	@property({ type: Boolean })
 	disabled!: boolean;
 
 	/**
 	 * Defines the action design.
 	 *
-	 * @type {sap.ui.webc.main.types.ButtonDesign}
-	 * @defaultvalue "Transparent"
+	 * @default "Transparent"
 	 * @public
-	 * @name sap.ui.webc.fiori.NotificationAction.prototype.design
 	 */
 	@property({ type: ButtonDesign, defaultValue: ButtonDesign.Transparent })
 	design!: `${ButtonDesign}`;
@@ -80,10 +68,8 @@ class NotificationAction extends UI5Element {
 	 * SAP-icons font provides numerous built-in icons. To find all the available icons, see the
 	 * <ui5-link target="_blank" href="https://sdk.openui5.org/test-resources/sap/m/demokit/iconExplorer/webapp/index.html">Icon Explorer</ui5-link>.
 	 *
-	 * @type {string}
-	 * @defaultvalue ""
+	 * @default ""
 	 * @public
-	 * @name sap.ui.webc.fiori.NotificationAction.prototype.icon
 	 */
 	@property()
 	icon!: string;
@@ -92,9 +78,9 @@ class NotificationAction extends UI5Element {
 	 * Fires a custom event "click".
 	 * <b>Note:</b> Called by NotificationListItem and NotificationListGroupItem components.
 	 *
-	 * @param { MouseEvent } e
+	 * @param e
 	 * @protected
-	 * @returns { boolean } false, if the event was cancelled (preventDefault called), true otherwise
+	 * @returns false, if the event was cancelled (preventDefault called), true otherwise
 	 */
 	fireClickEvent(e: MouseEvent): boolean {
 		return this.fireEvent<NotificationActionClickEventDetail>("click", {

diff --git a/packages/fiori/src/NotificationListGroupItem.ts b/packages/fiori/src/NotificationListGroupItem.ts
@@ -78,12 +78,9 @@ type NotificationListGroupItemToggleEventDetail = {
  * <br>
  * <code>import "@ui5/webcomponents/dist/NotificationAction.js";</code> (optional)
  * @constructor
- * @author SAP SE
- * @alias sap.ui.webc.fiori.NotificationListGroupItem
- * @extends sap.ui.webc.fiori.NotificationListItemBase
- * @tagname ui5-li-notification-group
+ * @extends NotificationListItemBase
  * @since 1.0.0-rc.8
- * @appenddocs sap.ui.webc.fiori.NotificationAction
+ * @implements {IListItem}
  * @public
  */
 @customElement({
@@ -104,25 +101,20 @@ type NotificationListGroupItemToggleEventDetail = {
  * Fired when the <code>ui5-li-notification-group</code> is expanded/collapsed by user interaction.
  *
  * @public
- * @event sap.ui.webc.fiori.NotificationListGroupItem#toggle
  */
 @event("toggle")
 class NotificationListGroupItem extends NotificationListItemBase {
 	/**
 	 * Defines if the group is collapsed or expanded.
-	 * @type {boolean}
-	 * @defaultvalue false
-	 * @name sap.ui.webc.fiori.NotificationListGroupItem.prototype.collapsed
+	 * @default false
 	 * @public
 	 */
 	@property({ type: Boolean })
 	collapsed!: boolean;
 
 	/**
 	 * Defines if the items <code>counter</code> would be displayed.
-	 * @type {boolean}
-	 * @defaultvalue false
-	 * @name sap.ui.webc.fiori.NotificationListGroupItem.prototype.showCounter
+	 * @default false
 	 * @public
 	 */
 	@property({ type: Boolean })
@@ -132,9 +124,6 @@ class NotificationListGroupItem extends NotificationListItemBase {
 	 * Defines the items of the <code>ui5-li-notification-group</code>,
 	 * usually <code>ui5-li-notification</code> items.
 	 *
-	 * @type {sap.ui.webc.fiori.INotificationListItem[]}
-	 * @slot items
-	 * @name sap.ui.webc.fiori.NotificationListGroupItem.prototype.default
 	 * @public
 	 */
 	@slot({ type: HTMLElement, "default": true })

diff --git a/packages/fiori/src/NotificationListItem.ts b/packages/fiori/src/NotificationListItem.ts
@@ -14,6 +14,7 @@ import Icon from "@ui5/webcomponents/dist/Icon.js";
 import Popover from "@ui5/webcomponents/dist/Popover.js";
 import WrappingType from "@ui5/webcomponents/dist/types/WrappingType.js";
 import NotificationListItemBase from "./NotificationListItemBase.js";
+import type { INotificationListItem } from "./Interfaces";
 
 // Icons
 import "@ui5/webcomponents-icons/dist/overflow.js";
@@ -69,28 +70,18 @@ type Footnote = Record<string, any>;
  * <h3>Usage</h3>
  * The component can be used in a standard <code>ui5-list</code>.
  *
- * <h3>CSS Shadow Parts</h3>
- *
- * <ui5-link target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/CSS/::part">CSS Shadow Parts</ui5-link> allow developers to style elements inside the Shadow DOM.
- * <br>
- * The <code>ui5-li-notification</code> exposes the following CSS Shadow Parts:
- * <ul>
- * <li>title-text - Used to style the titleText of the notification list item</li>
- * </ul>
- *
  * <h3>ES6 Module Import</h3>
  *
  * <code>import "@ui5/webcomponents/dist/NotificationListItem.js";</code>
  * <br>
  * <code>import "@ui5/webcomponents/dist/NotificationAction.js";</code> (optional)
  * @constructor
- * @author SAP SE
- * @alias sap.ui.webc.fiori.NotificationListItem
- * @extends sap.ui.webc.fiori.NotificationListItemBase
- * @tagname ui5-li-notification
- * @appenddocs sap.ui.webc.fiori.NotificationAction
+ * @extends NotificationListItemBase
  * @since 1.0.0-rc.8
+ * @implements {INotificationListItem}
+ * @implements {IListItem}
  * @public
+ * @csspart title-text - Used to style the titleText of the notification list item
  */
 @customElement({
 	tag: "ui5-li-notification",
@@ -107,18 +98,16 @@ type Footnote = Record<string, any>;
 })
 
 @event("_press")
-class NotificationListItem extends NotificationListItemBase {
+class NotificationListItem extends NotificationListItemBase implements INotificationListItem {
 	/**
 	* Defines if the <code>titleText</code> and <code>description</code> should wrap,
 	* they truncate by default.
 	*
 	* <br><br>
 	* <b>Note:</b> by default the <code>titleText</code> and <code>description</code>,
 	* and a <code>ShowMore/Less</code> button would be displayed.
-	* @type {sap.ui.webc.main.types.WrappingType}
-	* @defaultvalue "None"
+	* @default "None"
 	* @public
-	* @name sap.ui.webc.fiori.NotificationListItem.prototype.wrappingType
 	* @since 1.0.0-rc.15
 	*/
 	@property({ type: WrappingType, defaultValue: WrappingType.None })
@@ -149,20 +138,14 @@ class NotificationListItem extends NotificationListItemBase {
 	* we recommend using avatars with 2rem X 2rem in size (32px X 32px). In case you are using the <code>ui5-avatar</code>
 	* you can set its <code>size</code> property to <code>XS</code> to get the required size - <code>&lt;ui5-avatar size="XS">&lt;/ui5-avatar></code>.
 	*
-	* @type {sap.ui.webc.main.IAvatar}
-	* @slot
 	* @public
-	* @name sap.ui.webc.fiori.NotificationListItem.prototype.avatar
 	*/
 	@slot()
 	avatar!: Array<HTMLElement>;
 
 	/**
 	* Defines the elements, displayed in the footer of the of the component.
-	* @type {HTMLElement[]}
-	* @slot
 	* @public
-	* @name sap.ui.webc.fiori.NotificationListItem.prototype.footnotes
 	*/
 	@slot({ type: HTMLElement, individualSlots: true })
 	footnotes!: Array<HTMLElement>;
@@ -174,10 +157,7 @@ class NotificationListItem extends NotificationListItemBase {
 	* <br><br>
 	* <b>Note:</b> Although this slot accepts HTML Elements, it is strongly recommended that you only use text in order to preserve the intended design.
 	*
-	* @type {Node[]}
-	* @slot description
 	* @public
-	* @name sap.ui.webc.fiori.NotificationListItem.prototype.default
 	*/
 	@slot({ type: Node, "default": true })
 	description!: Array<Node>;