index html

How to use JSDoc with SAPUI5 Tooling?

Today will look into generating JSDoc with SAPUI5 Tooling. Let’s bring back that missing documentation from your project.

With the recent forced update from SAP Web IDE to move from Grunt to UI5-Tooling for SAPUI5 build process, our former JSDoc generator becomes deprecated.

Newly, created projects will now use the YAML as a task runner configuration. And our goal is to utilize the standard builder with minimal changes to our project.

Prerequisites

For you to be able to run ui5.yaml with jsdoc, you need the following:

Adding dependencies

First is to add dev dependencies to our SAPUI5 project. Modify your package.json and the following lines:

Adding JSDoc Configuration

Next is to create our jsdoc configuration. Create a jsdoc.conf.json file on the root of the project directory.

jsdoc.conf.json
jsdoc.conf.json

 

Copy the following lines of configuration:

There are few configurations from above we should take note of.

source

The source segment pertains to which directory our JavaScript files will be coming from.

opts

The opts segment specifies the general options of our jsdoc output.

You can view all command-line options from here.

Create JSDoc Configuration Runner

Next is to write a script that will execute our jsdoc.conf.json. Create a file in \lib\tasks\generateJsDoc.js. You can place this file anywhere but it’s better to have it under lib outside our webapp directory.

generateJsDoc.js
generateJsDoc.js

Open the file and enter the following lines:

What we did hear is to create a custom task implementation, which ui5.yaml will execute after the standard SAPUI5 tooling tasks. Later we will use this custom task and append it to out ui5.yaml.

Add Custom UI5 Builder Tasks

Next step is to add our custom task to our ui5.yaml. You can refer to this document for a more detailed explanation.

We added a new task generateJsDoc which is executed after webide-extension-task-resources. The task now refers to our custom task lib/tasks/generateJsDoc.js.

Note: you may encounter an error (yamlValidator) no error line supplied by yaml parser which is related to out task extension. This can be ignored.

Build SAPUI5 project

You can now build your SAPUI5 project thru Build->Build Project on your menu bar.

build project
build project
docs
docs

You can see that the project now includes the jsdoc build process and generated a doc folder in our workspace. You can also run the project with docs\<project_name>\<version>\index.html, which outputs like this:

index html
index html

And that’s it! now you can build your jsdoc documentation together with ui5-tooling. Don’t forget to adjust the jsdoc configuration base on your preference.

If you find this post helpful, you may want to check out some of our tutorials here. Don’t forget to subscribe or drop a comment below. Cheers!

Leave a Reply

8 comments

  1. Hi,

    Thanks for this valuable lesson.

    I have one question:

    I’m using SAP Web IDE to develop and build my apps. You’ve mentioned that we need Node version 8.5 or higher to execute this task. Do you know how to check what’s the current Node.js version in SAP Web IDE? When I click “Build” I can see in the console ‘[INFO] Preparing node environment’, but I’m wondering how is Node.js environment connected with the IDE. I wasn’t able to find any tips or official documentations.

    Best regards,
    Ade

    1. Hi Ade,

      Yes, there’s no official document as of today where you can check the node version installed, at least that I’m aware of.
      But since we have access to console scripting via our generateJsDoc.js, we can easily modify the script.

      Here my excerpt.

      /* the rest of generateJsDoc.js */
      execSync('node -v', {
      stdio: 'inherit'
      });

      Thanks,
      Gin

  2. Thanks! Very very useful!
    I’m still struggling understanding ui5-tooling in a Web-IDE context because I think is not very well documented.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.