[documentation]: refactor documentation

[nnaydenow]

This issue is follow up of https://github.com/SAP/ui5-webcomponents/issues/6958

Background:

Right now, if someone wants to write documentation for their code, they have to use namespaces (like "sap.ui.webc.main"). This is because JSDoc doesn't understand where to assign the comments otherwise. This makes things a bit harder for developers. So, we decided to use a different documentation standard, which is called "custom-elements-manifest." To switch from "api.json" to "custom-elements.json," we need to replace the JSDoc plugin with "custom-elements-manifest/analyzer."

Once we make this change, the way we write our documentation will be different. We'll have to update our JSDoc comments by getting rid of the namespaces, removing tags that we don't use anymore, and so on.

Expectation:

Revise documentation using the details provided below.

---

Table on contents

1. JSDOC changes
   1. Class tags
   2. Property and getter (readonly property) tags
   3. Slot tags
      1. Property slot
      2. Unnamed slot
   4. Event tags
      1. Event tags
      2. Event parameter tags
   5. Method tags
   6. CSS Part
   7. Enum and enum member tags
   8. Interface tags
2. Interface changes

---

JSDOC changes

Class tags

Tag	Description	Accepted types	Examples
@class	Defines the constructor	boolean	@class
@constructor		boolean	@constructor
@public / @protected / @private	Defines the privacy of the class	-	@public @protected @private
@since	Defines the version when the class was introduced	string	@since 1.2.0
@deprecated	Defines whether the class is deprecated	boolean | string	@depreaceted @deprecated version 1.4.0
@abstract	Defines whether the component is abstract (doesn't have ShadowDOM)	boolean	@abstract
@implements	Defines the interfaces that the component implements	-	@implements {ShowcaseType}
@extends	Defines the superclass of the component	-	@extends ShowcaseType
@slot	-	-	See more
@csspart	-	-	See more

/**
* @class
* Class description showcase
*
* @slot {ShowcaseType[]} default - Unnamed slot description showcase
*
* @csspart testPart - CSS Part description showcase
*
* @constructor
* @extends UI5Element
* @since 1.2.0
* @deprecated 1.4.0
* @public
* @abstract
* @implements {ShowcaseType}
* @implements {ShowcaseType2}
*/
@customElement("ui5-test-component")
class TestComponent extends UI5Element implements ShowcaseType, ShowcaseType2 {

Note: Class name is automatically generated and @alias tag is redudant

Note: Tag name is automatically generated and @tagName is redundant

Note: If the component implements more than 1 interface use @implements tag for every interface, instead of separating them with comma.

Property and getter (readonly property) tags

Tag	Description	Accepted types	Examples
@public / @protected / @private	Defines the privacy of the property	-	@public @protected @private
@since	Defines the version when the property was introduced	string	@since 1.2.0
@deprecated	Defines whether the property is deprecated	boolean | string	@depreaceted @deprecated version 1.4.0
@default (required for public properties/getters)	Defines the default value of the property	string	@default "myDefaultValue"
@formProperty	Defines whether the property value should be used in a form (Angular / React)	boolean	@formProperty
@formEvents	Defines which events should change property value	string	@formEvents change input

/**
* Property description showcase
*
* @public
* @since 1.2.0
* @deprecated 1.4.0
* @default "myDefaultValue"
* @formProperty
* @formEvents change input
*/
@property({ defaultValue: "myDefaultValue" })
property!: string;

Note: Type is autmatially calculated from the accesor name.

Note: Property name is automatically generated from accessor name and @name tag is redundant.

Slot tags

Property slot

Property slot is the slot that has accessor

Tag	Description	Accepted types	Examples
@public / @protected / @private	Defines the privacy of the slot	-	@public @protected @private
@since	Defines the version when the slot was introduced	string	@since 1.2.0
@deprecated	Defines whether the slot is deprecated	boolean | string	@depreaceted @deprecated version 1.4.0

/**
* Property slot description showcase
*
* @public
* @since 1.2.0
* @deprecated 1.4.0
*/
@slot({ type: HTMLElement, "default": true })
propertySlot!: Array<IIcon>;

Note: Slot name is automatically generated from accessor name and @slot tag is redundant.

Note: Type is automatically calculated from the accessor type

Note: If the default is set to true inside the decorator, the slot will appear as default.

Unnamed slot

Property slot is the default slot that doesn't have accessor. This slot is declared inside class comment using @slot tag.

/**
* @class
* ...
*
* @slot {ShowcaseType[]} default - Unnamed slot description showcase
* ...
*/
@customElement("ui5-test-component")
class TestComponent extends UI5Element {

Event tags

Event tags

Tag	Description	Accepted types	Examples
@param	Defines the event details parameters	-	@param {ShowcaseType} testParameter description
@public / @protected / @private	Defines the privacy of the event	-	@public @protected @private
@since	Defines the version when the event was introduced	string	@since 1.2.0
@deprecated	Defines whether the event is deprecated	boolean | string	@depreaceted @deprecated version 1.4.0
@allowPreventDefault	Defines whether the event is preventable	boolean	@allowPreventDefault
@native	Defines whether the event is native event	boolean	@native

/**
* Event description showcase
* @public
* @since 1.2.0
* @deprecated 1.4.0
* @param {ShowcaseType} testParameter description
* @allowPreventDefault
* @native
*/
@event("eventWithDetails", {
    detail: {
        /**
        * @public
        * @since 1.2.0
        * @deprecated 1.4.0
        */
        testParameter: { type: HTMLElement }
    },
})
class TestComponent extends UI5Element {

Event parameter tags

Now, you can specify

Tag	Description	Accepted types	Examples
@public / @protected / @private (required if there is a @param tag with the same name)	Defines the privacy of the event parameter	-	@public @protected @private
@since	Defines the version when the event parameter was introduced	string	@since 1.2.0
@deprecated	Defines whether the event parameter is deprecated	boolean | string	@depreaceted @deprecated version 1.4.0

@event("eventWithDetails", {
    detail: {
        /**
        * @public
        * @since 1.2.0
        * @deprecated 1.4.0
        */
        testParameter: { type: HTMLElement }
    },
})
class TestComponent extends UI5Element {

Note: With these tags only deprecated, since and privacy status could be changed. If you want to change the description use @param tag in the event description. Note: Now, you have to specify the privacy of the parameter with privacy tag and also to describe the parameter in event comment.

Method tags

Tag	Description	Accepted types	Examples
@param	Defines the method's parameters	-	@param param1 parameter description showcase @param {ShowcaseType} [param2] optional parameter description showcase
@public / @protected / @private	Defines the privacy of the method	-	@public @protected @private
@since	Defines the version when the method was introduced	string	@since 1.2.0
@deprecated	Defines whether the method is deprecated	boolean | string	@depreaceted @deprecated version 1.4.0
@returns	Defines the return value description	-	@returns return description showcase

/**
* Shows the popover.
* @param param1 parameter description showcase
* @param [param2] optional parameter description showcase
* @public
* @since 1.2.0
* @deprecated 1.4.0
* @returns description of return
*/
static methodName(param1: Array<ShowcaseType>, param2 = ShowcaseType.Type1): boolean {}

Note: Parameters type and return types is generated automatically

Note: Method name is automatically generated from accessor name and @method / @name tag is redundant.

Note: @async method is redundant because only return type is used

Note: @static tag is redundant because it's automatically calculated when the method is static

CSS Part

YOu can defined css part inside class comment using @csspart tag.

/**
* @class
* ...
*
* @csspart testPart - CSS Part description showcase
* ...
*/
@customElement("ui5-test-component")
class TestComponent extends UI5Element {

Enum and enum member tags

Tag	Description	Accepted types	Examples
@public / @protected / @private (required for enum members)	Defines the privacy of the enum / enum member	-	@public @protected @private
@since	Defines the version when the enum / enum member was introduced	string	@since 1.2.0
@deprecated	Defines whether the enum / enum member is deprecated	boolean | string	@depreaceted @deprecated version 1.4.0

/**
 * Enum description showcase
 *
 * @public
 * @since 1.2.0
 * @deprecated 1.4.0
 */
enum ShowcaseType {
    /**
     * Enum member description showcase
     *
     * @public
     * @since 1.2.0
     * @deprecated 1.4.0
     */
    Type1 = "Type1",
}

Note: Enum name is automatically generated from accessor name and @alias tag is redundant.

Interface tags

Tag	Description	Accepted types	Examples
@public / @protected / @private	Defines the privacy of the interface	-	@public @protected @private
@since	Defines the version when the interface was introduced	string	@since 1.2.0
@deprecated	Defines whether the interface is deprecated	boolean | string	@depreaceted @deprecated version 1.4.0

/**
 * Interface description showcase
 *
 * @public
 * @since 1.2.0
 * @deprecated 1.4.0
 */
interface ShowcaseType {
    property: string;
}

Note: Interface name is automatically generated from accessor name and @name tag is redundant.

Interface changes

In order to remove sap.ui.webc.main/fiori namespaces we have to replace variable declared interfaces with a TypeScript declared interfaces. At the moment interfaces are only markes but for some of the markers a real interfaces exist so the changes are following:

• Interface that can't be transformed to a real interface

  ## Before
  const IButton = "sap.ui.webc.main.IButton";
  
  ## After
  interface IButton extends HTMLElement { }

• Interface that can be transformed to a real interface

  ## Before
  const IComboBoxItem = "sap.ui.webc.main.IComboBoxItem";
  
  ## After
  interface IComboBoxItem extends UI5Element {
    text: string,
    focused: boolean,
    isGroupItem: boolean,
    selected?: boolean,
    additionalText?: string,
  }

NOTE: If the interface is created to describe abstract component (component that doesn't have template) we remove the interface and start to use the class since.

Fixes: #7388 #7075 #6306

[hristop]

Internal BLI was created: FIORITECHP1-28822