ui5-jsdoc-generator
Creates automatic documentation for control libraries done in ui5
Install
npm install ui5-jsdoc-generator --save-dev
Setup
node ./node_modules/ui5-jsdoc-generator/bin/ui5-jsdoc-generator.js --input=inputFolder --output=outputFolder
Template
Create a file (templates/template.html) inside your web project with the following content:
@class
<b> #__CONTROL_NAME__# </b> <br>
<i> #__CONTROL_DESCRIPTION__#</i>
<br>
<br>
Supported settings are:
<ul>
<li>Properties
<ul>#__PROPERTIES__#</ul>
</li>
<li>Aggregations
<ul>#__AGGREGATIONS__#</ul>
</li>
<li>Associations
<ul>#__ASSOCIATIONS__#</ul>
</li>
<li>Events
<ul>#__EVENTS__#</ul>
</li>
</ul>
<br>
In addition, all settings applicable to the base type {@link #__BASE_CLASS__#} can be used as well.
@extends #__BASE_CLASS__#
@author #__AUTHOR__#
@version #__VERSION__#
@public
@alias #__CONTROL_NAME__# JSDoc integration
ui5-jsdoc-generator can be easily integrated with jsdoc using an npm script:
Run the following commands
-
npm init(note: we're creating package.json) npm install jsdoc --save-devnpm install ui5-jsdoc-generator --save-dev
Edit the script tag of the package.json with the following information
{
"name": "test",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"ui5JSDoc":"node ./node_modules/ui5-jsdoc-generator/bin/ui5-jsdoc-generator.js --input=inputControlFolder --output=tmpJSDoc",
"jsdoc":"./node_modules/.bin/jsdoc -r tmpJSDoc -d tmp ",
"doc": "npm run ui5JSDoc && npm run jsdoc"
},
"author": "",
"license": "ISC"
}And finally, execute npm run doc
Why ?
A common ui5 control looks like the following code -
sap.ui.define(['sap/ui/core/Control'], function(base) {
'use strict';
var Control = base.extend('namespace.controlname', {
metadata: {
properties: {
property1: { type: "boolean", defaultValue: true },
property2: { type: "string", defaultValue: "defaultValueString" }
},
aggregations: {
agg1: { type: 'namespace.aggregation' }
},
events: { click: {} },
}
});
Control.prototype.init = function() {};
return Control;
}, true);Everything is fine until the alarm rings with the following sound 'where is the documentation?'. No problem sir! We have a "quick" solution on mind. You go through every control in your library adding the jsdoc annotations manually. Now everything looks like:
sap.ui.define(['sap/ui/core/Control'], function(base) {
'use strict';
/**
* @class
* <b> namespace.controlname </b> <br>
* <i> this is the control description</i>
* Supported settings are:
* <ul>
* <li>Properties
* <ul>
* <li>property1 type: boolean defaultValue: true</li>
* <li>property2 type: string defaultValue: defaultValueString</li>
* </ul>
* </li>
* <li>Aggregations
* <ul><li>agtest type: namespace.aggregation</li></ul>
* </li>
* <li>Associations
* <ul>no value</ul>
* </li>
* <li>Events
* <ul><li>click</li></ul>
* </li>
*
* In addition, all settings applicable to the base type {@link sap.ui.core.Control} can be used as well.
*
* @extends sap.ui.core.Control
*
* @author author name
* @version 1.0.0
*
* @public
* @alias namespace.controlname
*
**/
var Control = base.extend('namespace.controlname', {
metadata: {
properties: {
property1: { type: "boolean", defaultValue: true },
property2: { type: "string", defaultValue: "defaultValueString" }
},
aggregations: {
agg1: { type: 'namespace.aggregation' }
},
events: { click: {} },
}
});
Control.prototype.init = function() {};
return Control;
}, true);Why are we adding all that information manually when ui5 stores everything into the metadata ? Isn't it unnecessary ? What happends if we add a new property? We need to change the header comments once again! To avoid all those problems just change the control in the following way -
sap.ui.define(['sap/ui/core/Control'], function(base) {
'use strict';
// @ui5JSDoc
var Control = base.extend('namespace.controlname', {
metadata: {
properties: {
property1: { type: "boolean", defaultValue: true },
property2: { type: "string", defaultValue: "defaultValueString" }
},
aggregations: {
agg1: { type: 'namespace.aggregation' }
},
events: { click: {} },
ui5JSDoc: {
description: "this is a new control",
author: "the best developer ever!"
version: "0.0.1",
baseClass: "sap.ui.core.Control"
}
}
});
Control.prototype.init = function() {};
return Control;
}, true);ui5-jsdoc-generator will parse the metadata structure and generate the necessary notations for jsdoc automagically
