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:

"devDependencies": {
    "@ui5/cli": "1.7.0",
    "@sap/ui5-builder-webide-extension": "1.0.9",
    "jsdoc": "3.6.3",
    "minami": "^1.2.3"
},

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:

{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc"]
    },
    "source": {
        "include": ["./package.json", "./README.MD", "webapp"],
        "includePattern": ".+\.js(doc)?$",
        "excludePattern": "(^|\/|\\)_"
    },
    "plugins": ["node_modules/jsdoc/plugins/markdown"],
    "templates": {
        "cleverLinks": true,
        "monospaceLinks": false,
        "useLongnameInNav": false,
        "showInheritedInNav": true
    },
    "opts": {
        "changelog": "./CHANGES.MD",
        "destination": "./docs",
        "recurse": true,
        "private": true,
        "encoding": "utf-8",
        "mainPageTitle": "Home",
        "template": "node_modules/minami"
    }
}

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.

"source": {
    // look for js files here
    "include": ["./package.json", "./README.MD", "webapp"], 
    // read any file ending with js or jsdoc
    "includePattern": ".+\.js(doc)?$",
    // Any file starting with an underscore, or in a directory starting with an underscore, will be ignored
    "excludePattern": "(^|\/|\\)_"
},

opts

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

"opts": {
    // specify the changelog
    "changelog": "./CHANGES.MD",
    // where the output jsdoc files will be
    "destination": "./docs",
    // will jsdoc parse recursively
    "recurse": true,
    // render private properties
    "private": true,
    // file encoding
    "encoding": "utf-8",
    // title of the jsdoc website
    "mainPageTitle": "Home",
    // template to use for generation
    "template": "node_modules/minami"
}

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:

/**
 * Custom task example
 *
 * @param {Object} parameters Parameters
 * @param {module:@ui5/fs.DuplexCollection} parameters.workspace DuplexCollection to read and write files
 * @param {module:@ui5/fs.AbstractReader} parameters.dependencies Reader or Collection to read dependency files
 * @param {Object} parameters.options Options
 * @param {string} parameters.options.projectName Project name
 * @param {string} [parameters.options.projectNamespace] Project namespace if available
 * @param {string} [parameters.options.configuration] Task configuration if given in ui5.yaml
 * @returns {Promise<undefined>} Promise resolving with <code>undefined</code> once data has been written
 */
module.exports = async function ({
    workspace,
    dependencies,
    options
}) {
    // For logging purposes
    console.log("----------------------RUNNING JSDOC----------------------");

    const {
        execSync
    } = require('child_process');
    // will execute the standard jsdoc command using our configuration.
    execSync('jsdoc -c ./jsdoc.conf.json --verbose', {
        stdio: 'inherit'
    });

    // For logging purposes
    console.log("----------------------END OF RUNNING JSDOC----------------------");

};

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.

# ... The rest of the ui5.yaml code
    - name: webide-extension-task-resources
      afterTask: webide-extension-task-lint
      configuration:
        nameSpace: com/test
    - name: generateJsDoc
      afterTask: webide-extension-task-resources
      configuration:
        color: blue
---
# Task extension as part of your project
specVersion: "1.0"
kind: extension
type: task
metadata:
  name: generateJsDoc
task:
  path: lib/tasks/generateJsDoc.js

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!

8 thoughts on “How to use JSDoc with SAPUI5 Tooling?”

  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

    Reply
    • 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

      Reply
  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.

    Reply

Leave a Comment

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