Typescript and JSDoc

[tobiashofmann]

Is your feature request related to a problem? Please describe.

UI5 cli offers a built-in task for generating JSDoc: ui5 build jsdoc

While this works for JS based UI5 projects, this task won't work for a TypeScript project. Here, the TS coding is transformed by babel to JavaScript and the comments are removed. Using now the jsdoc task will result in no JSDoc being generated, as the JS source files in webapp do not contain the needed JSDoc comments. Even when the TS sources contain valid JSDoc comments, no JSDoc artifacts are generated using ui5 tooling.

Describe the solution you'd like

Maybe ui5 tooling can include support for JSDoc in TS files? So that ui5 build jsdoc is able to generate the JSDoc artifacts from the TS source? Or maybe include the usage of typedoc in the docs? In that case, maybe it is better to completely remove support for JSDoc from the ui5 tooling and inform the user to generate it manually in a seperate build step?

Describe alternatives you've considered

Include the JSDoc comments in the TS to JS transformation so the jsdoc works on the generated JS sources. This should not be considered as the doc is for the TS source and might inlcude TS specific information. Also, the documentation should be created for what the developer writes, and not on generated JS files. An alternative is to remove JSDoc from ui5 tooling and let the user generate the docs in a seperate build step (manually or via a build pipeline). Not using JSdoc at all is not an option, as the documentation is an important asset.

[RandomByte]

Hi Tobias, sorry for the late response and thank you very much for this feature request.

I think you summarized the situation and possible solutions very well. JSDoc itself can't parse TypeScript sources (also see jsdoc/jsdoc#1917). And the UI5-Specific JSDoc plugin is unlikely to add support for that either (@codeworrior correct me if I'm wrong).

We anyways plan to split the JSDoc generation from the standard UI5 Tooling and make it a custom task. I can imagine this would open the door for developers to fork it and add support for parsing TypeScript directly.