Build TypeDoc of autogenerated interfaces

[CarlosOrozco88]

Hello, I'm creating a UI5 library in TypeScript and I also want to use TypeDoc to generate the documentation.

The problem I've encountered is that the JSDoc comments I add are not automatically added to the *.gen.d.ts files, so the documentation lacks that information. Am I doing something wrong or is this something that hasn't been considered yet?

For example: My control Popup.ts metadata object:

static readonly metadata: object = {
    library: 'dev.carlosorozco.ui5Extra',
    properties: {
      /** Title of the Popup */
      title: {
        type: 'string',
        group: 'Appearance',
        defaultValue: ''
      },
      ...
    }
}

Auto generates this interface:

/**
 * Interface defining the settings object used in constructor calls
 */
interface $PopupSettings extends $ManagedObjectSettings {
    title?: string | PropertyBindingInfo;
    ....
}

Then, when I run TypeDoc it builds this output:

Expected behaviour:

/**
 * Interface defining the settings object used in constructor calls
 */
interface $PopupSettings extends $ManagedObjectSettings {
    /** Title of the Popup */
    title?: string | PropertyBindingInfo;
    ....
}

Then Typedoc shows the text:

I'm not sure if it's something that should be done by 'ui5-interface-generator' or if I've approached it incorrectly and should do it another way

[akudev]

Hi Carlos, you are right: the documentation is not copied over to the *gen.d.ts file. Actually, this is the first entry of the readme's TODO list: https://github.com/SAP/ui5-typescript/tree/main/packages/ts-interface-generator#todo So it's definitely something that needs to be done, it just hasn't yet.

[CarlosOrozco88]

Oh I'm so sorry, I had not seen it.

Thank you so much

[akudev]

No problem, it's good to have this topic more visible.

[akudev]

I've been working on this. I plan for an option that decides how much JSDoc is generated: none, minimal and verbose. Where "minimal" roughly means "the JSDoc that is written by the developer" and "verbose" means: "also all the boilerplate stuff that is generated automatically also for UI5's own controls.

Verbose:

        /**
         * Sets a new value for property "subtext".
         *
         * The text that appears below the main text.
         *
         * @since 1.0
         * @deprecated since 2.0 use something else
         * When called with a value of "null" or "undefined", the default value of the property will be restored.
         *
         * @param subtext New value for property "subtext"
         * @returns Reference to "this" in order to allow method chaining
         */
        setSubtext(subtext: string): this;

Minimal:

        /**
         * The text that appears below the main text.
         *
         * @since 1.0
         * @deprecated since 2.0 use something else
         */
        setSubtext(subtext: string): this;

(In the settings object only the minimal version is used anyway, this distinction is only relevant for the generated methods.)

I'm wondering what sould be the default: minimal or verbose? The amount of JSDoc for the large number of generated aggregation-related methods can be significant...

If anyone has a strong opinion, let me know.

[akudev]

This was implemented now in version 0.6.0. Please give feedback.