I am just making my first UI5 Typescript project with the wonderful NPM packages @sapui5/ts-types-esm and @openui5/ts-types-esm introduced at UI5Con (https://openui5.org/ui5con/onair2021/) by Andreas Kunz .
Now, me trying to do everything right, I am wondering how to generate the documentation correctly from my code annotations? Anybody any pointers or thoughts on this?
The UI5 CLI command "ui5 build jsdoc" does not feel right and, at least in my case, does not yield good results. After having a look at the transpiled JS I suppose comments from the TS files are ignored by BABEL. Obviously the UI5 tools cannot pick up what is not there ;-)
Manually inserting JSDoc comments in the generated JS files is not an option for me. Though it seems the only way to use "ui5 build jsdoc" it just feels wrong. In addition I am too lazy to do it every time I transpile.
From my (architectural) point of view it does make sense to directly comment the real TS sources. I could introduce a third party tool (https://typedoc.org/) to generate the docs. However I like to keep things lean. Meaning: An integration into the UI5 Tooling would be ideal. One tool to do the job, less dependencies that I need to take care of. Of course the transpiler script might be another vector to solve this by including comments in the generated JS files.
Hope someone likes to share some thoughts on this :-)