UI5 Annotater

Automatically add JSDoc comments for sap.ui.define.

Usage

Open a shell in your projects root folder and execute:

ui5-annotater

You may provide a ui5-annotater.json-file in order to configure the compiler. As of now it only allows you to configure a blacklist for folders, which are not to be edited (useful for ui5 build-dists or Fiori-Elements apps).

{
  "blacklist": ["dist"]
}

In order to make your editor use TypeScript, you also have to add a tsconfig.json:

{
  "compilerOptions": {
      "module": "none",
      "target": "es2018",
      "noEmit": true,
      "checkJs": true,
      "allowJs": true,
      "types": ["@openui5/ts-types"]
  },
  "exclude": ["node_modules"]
}

@openui5/ts-types needs to be installed with npm i --save-dev @openui5/ts-types. You may also use @sapui5/ts-types or specify a UI5 version with npm i --save-dev @openui5/[email protected] (though not all versions are supported).

Motivation

TypeScript can consume JSDoc in order to resolve type declarations. The callback in sap.ui.define takes UI5 libraries as arguments. Having types for those provides a quick way to access API documentation and may help to ensure their correct usage.

UI5 Annotater walks through UI5 projects and automatically adds JSDoc declarations. This allows you to gain TypeScript developer comfort for existing UI5 projects at no cost.

The benefits are inferior to writing TypeScript code, but this is nice for:

• legacy projects,
• projects where we don't want an extra build-step and
• having a taste of TypeScript developer experience.

Example

Here is an untyped UI5 file:

The correct JSDoc-Declaration (which can be autogenerated with UI5 Annotater) shows that there is a mistake:

The error message Argument of type '"oneWay"' is not assignable to parameter of type 'BindingMode'. helps us to find the problem and fix it. We need to provide BindingMode as the argument instead of "oneWay". Notice how TypeScript not only highlights the error, but also gives us auto-completion: