How to generate an JSDoc documentation for your UI5 application in the SAP Web IDE (UI5 Tooling & Grunt)

Newly generated projects in the SAP Web IDE stopped using Grunt as Taskrunner. Instead the UI5 Tooling gets used, recognizable by the ui5.yaml. In addition to many out-of-the-box functionalities, UI5 Tooling allows us to create custom tasks. (For more information have a look at UI5 Tooling – Extensibility – Custom Tasks).

However, i wasn’t able to include JSDoc via a custom task. In order to use the advantages of UI5 Tooling, but also generate an JSDoc documentation i copied a solution that is also used by SAP for librarys generated via Web IDE – a mixture of UI5 Tooling and Grunt.

In the following, the necessary adjustements for newly generated projects are described.

Adjust the package.json

Add the following packages to the package.json:

• grunt
• grunt-run

Furthermore define a clean script and adjust the existing build script.

• clean script
  • "clean": "rm -rf dist" (delete the dist folder)
• build script
  • "build": "ui5 build --include-task=generateManifestBundle generateCachebusterInfo" (delete the --clean dest command, it get’s replaced by the clean script)

The package.json should look like the code shown below.

{
	"name": ">>application<<",
	"version": "0.0.1",
	"description": ">>description<<",
	"devDependencies": {
		"@ui5/cli": "1.13.0",
		"@sap/ui5-builder-webide-extension": "1.0.x",
		"grunt": "1.0.1",
		"grunt-run": "0.8.1"
	},
	"scripts": {
		"clean": "rm -rf dist",
		"build": "ui5 build --include-task=generateManifestBundle generateCachebusterInfo"
	},
	"ui5": {
		"dependencies": [
			"@sap/ui5-builder-webide-extension"
		]
	},
	"private": "true"
}

Create the Gruntfile.js

Create the Gruntfile.js file and paste the code snippet shown below.

module.exports = function (grunt) {
	"use strict";
	
	grunt.loadNpmTasks("grunt-run");
	
	grunt.initConfig({
		run: {
			options: {
				failOnError: true
			},
			build: {
				exec: "npm run build"
			},
			clean: {
				exec: "npm run clean"
			}
		}
	});
	
	grunt.registerTask("default", ["run:clean", "run:build"]);
};

So far we’ve changed a few things but the build process is the same as before despite the fact that the Gruntfile.js calls the scripts from the ui5.yaml. Well… and now we can call tasks in grunt like we used to do before UI5 Tooling was a thing and we can use the new features from UI5 Tooling.

Configure grunt-jsdoc

• Add the package grunt-jsdoc to the package.json.
• Adjust the Gruntfile.js
  • Load the jsdoc task
  • Configure the jsdoc task
  • Register the jsdoc task

The Gruntfile.js should look like the code shown below.

module.exports = function (grunt) {
	"use strict";

	grunt.loadNpmTasks("grunt-run");
	grunt.loadNpmTasks('grunt-jsdoc'); //load jsdoc task

	grunt.initConfig({
		run: {
			options: {
				failOnError: true
			},
			build: {
				exec: "npm run build"
			},
			clean: {
				exec: "npm run clean"
			}
		},
		jsdoc: { //configurate jsdoc task
			dist: {
				src: [
					'webapp/Component.js' //add other files here
				],
				options: {
					destination: 'doc'
				}
			}
		}
	});

	grunt.registerTask("default", ["run:clean", "run:build", "jsdoc"]); //added jsdoc task
};

That’s it. The build process is the same as before except that we also generate an JSDoc documentation of our application.

Your application doesn’t have a file called ui5.yaml? There is only the Gruntfile.js and in the package.json there is only one devDependencie called @sap/grunt-sapui5-bestpractice-build? Then check out this blog post: How to generate an JSDoc documentation for your UI5 application in the SAP Web IDE (Grunt)