Creates automatic documentation for control libraries done in ui5 Edit
npm install ui5-jsdoc-generatornpm install ui5-jsdoc-generator --save-devnode ./node_modules/ui5-jsdoc-generator/bin/ui5-jsdoc-generator.js --input=inputFolder --output=outputFolderhtml
@class
#__CONTROL_NAME__#
#__CONTROL_DESCRIPTION__#
Supported settings are:
- Properties
#__PROPERTIES__#
- Aggregations
#__AGGREGATIONS__#
- Associations
#__ASSOCIATIONS__#
- Events
#__EVENTS__#
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-dev
* npm install ui5-jsdoc-generator --save-devEdit the script tag of the package.json with the following information
`json
{
"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 docWhy ?
A common ui5 control looks like the following code -
`javascript
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:
`javascript
sap.ui.define(['sap/ui/core/Control'], function(base) {
'use strict';
/**
* @class
* namespace.controlname
* this is the control description
* Supported settings are:
*
* - Properties
*
* - property1 type: boolean defaultValue: true
* - property2 type: string defaultValue: defaultValueString
*
*
* - Aggregations
* - agtest type: namespace.aggregation
*
* - Associations
* no value
*
* - Events
* - click
*
*
* 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 - `javascript
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);
``