From bb60019502c71743cb977a8a03daf96abb1ddfb0 Mon Sep 17 00:00:00 2001 From: Florian Vogt Date: Tue, 12 May 2020 16:09:22 +0200 Subject: [PATCH] [INTERNAL] sap.ui.core: add default value to JSDoc Adding default values of function parameters to JSDoc conform notation Change-Id: Id780fe54f0791d4bf2830b2c0d6fd622a4e232a4 demo-kit-feedback: #2838 --- lib/jsdoc/ui5/plugin.js | 21 ++++++++++++++++++- src/sap.ui.core/src/sap/ui/core/Component.js | 4 ++-- .../src/sap/ui/core/ComponentMetadata.js | 6 +++--- src/sap.ui.core/src/sap/ui/core/Element.js | 4 ++-- src/sap.ui.core/src/sap/ui/core/Manifest.js | 10 ++++++--- src/sap.ui.core/src/sap/ui/core/Popup.js | 9 ++++---- .../src/sap/ui/core/routing/Router.js | 4 ++-- .../src/sap/ui/core/routing/Targets.js | 5 ++--- .../src/sap/ui/core/util/Export.js | 2 +- src/sap.ui.core/src/sap/ui/core/util/File.js | 2 +- .../src/sap/ui/core/util/MockServer.js | 4 ++-- 11 files changed, 46 insertions(+), 25 deletions(-) diff --git a/lib/jsdoc/ui5/plugin.js b/lib/jsdoc/ui5/plugin.js index 5de518580f53..2596b8f29e5c 100644 --- a/lib/jsdoc/ui5/plugin.js +++ b/lib/jsdoc/ui5/plugin.js @@ -1247,6 +1247,25 @@ function createAutoDoc(oClassInfo, classComment, node, parser, filename, comment return prefix + n.slice(0,1).toUpperCase() + n.slice(1); } + function generateParamTag(n, type, description, defaultValue){ + var s = "@param {" + info.type + "} "; + + if (defaultValue !== null){ + s += "[" + varname(n, type, true) + "="; + if (type === "string"){ + defaultValue = "\"" + defaultValue + "\""; + } + s += defaultValue + "]"; + + } else { + s += varname(n, type, true); + } + + s += " " + description; + + return s; + } + // add a list of the possible settings if and only if // - documentation for the constructor exists // - no (generated) documentation for settings exists already @@ -1431,7 +1450,7 @@ function createAutoDoc(oClassInfo, classComment, node, parser, filename, comment "When called with a value of null or undefined, the default value of the property will be restored.", "", info.defaultValue !== null ? "Default value is " + (info.defaultValue === "" ? "empty string" : info.defaultValue) + "." : "", - "@param {" + info.type + "} " + varname(n,info.type,true) + " New value for property " + n + "", + generateParamTag(n, info.type, "New value for property " + n + "", info.defaultValue), "@returns {" + oClassInfo.name + "} Reference to this in order to allow method chaining", info.since ? "@since " + info.since : "", info.deprecation ? "@deprecated " + info.deprecation : "", diff --git a/src/sap.ui.core/src/sap/ui/core/Component.js b/src/sap.ui.core/src/sap/ui/core/Component.js index 7e9281f9b01f..0afa428da62c 100644 --- a/src/sap.ui.core/src/sap/ui/core/Component.js +++ b/src/sap.ui.core/src/sap/ui/core/Component.js @@ -2066,7 +2066,7 @@ sap.ui.define([ * @param {string[]} [mOptions.activeTerminologies] List of active terminologies. * The order of the given active terminologies is significant. The {@link sap.base.i18n.ResourceBundle ResourceBundle} API * documentation describes the processing behavior in more detail. - * Please have a look at this dev-guide chapter for general usage instructions: {@link topic:CPOUI5FRAMEWORK-57_Docu_Chapter Text Verticalization}. + * Please have a look at this dev-guide chapter for general usage instructions: {@link topic:eba8d25a31ef416ead876e091e67824e Text Verticalization}. * @param {object} [mOptions.settings] Settings of the new Component * @param {boolean|string|object} [mOptions.manifest=true] Whether and from where to load the manifest.json for the Component. * When set to any truthy value, the manifest will be loaded and evaluated before the Component controller. @@ -2158,7 +2158,7 @@ sap.ui.define([ * @param {string[]} [vConfig.activeTerminologies] List of active terminologies. * The order of the given active terminologies is significant. The {@link sap.base.i18n.ResourceBundle ResourceBundle} API * documentation describes the processing behavior in more detail. - * Please also have a look at this dev-guide chapter for general usage instructions: {@link topic:CPOUI5FRAMEWORK-57_Docu_Chapter Text Verticalization}. + * Please also have a look at this dev-guide chapter for general usage instructions: {@link topic:eba8d25a31ef416ead876e091e67824e Text Verticalization}. * @param {boolean} [vConfig.async] Indicates whether the Component creation should be done asynchronously; defaults to true when using the manifest property with a truthy value otherwise the default is false (experimental setting) * @param {object} [vConfig.asyncHints] @since 1.27.0 Hints for the asynchronous loading. * Beware: This parameter is only used internally by the UI5 framework and compatibility cannot be guaranteed. diff --git a/src/sap.ui.core/src/sap/ui/core/ComponentMetadata.js b/src/sap.ui.core/src/sap/ui/core/ComponentMetadata.js index 833007fa31fe..9106c8fa1c69 100644 --- a/src/sap.ui.core/src/sap/ui/core/ComponentMetadata.js +++ b/src/sap.ui.core/src/sap/ui/core/ComponentMetadata.js @@ -404,7 +404,7 @@ sap.ui.define([ * inside the manifest. The path syntax always starts with a slash (/). * * @param {string} sKey Either the manifest section name (namespace) or a concrete path - * @param {boolean} [bMerged] Indicates whether the custom configuration is merged with the parent custom configuration of the Component. + * @param {boolean} [bMerged=false] Indicates whether the custom configuration is merged with the parent custom configuration of the Component. * @return {any|null} Value of the manifest section or the key (could be any kind of value) * @public * @since 1.27.1 @@ -453,7 +453,7 @@ sap.ui.define([ * The configuration above can be accessed via sample.Component.getMetadata().getCustomEntry("my.custom.config"). * * @param {string} sKey Key of the custom configuration (must be prefixed with a namespace) - * @param {boolean} bMerged Indicates whether the custom configuration is merged with the parent custom configuration of the Component. + * @param {boolean} [bMerged=false] Indicates whether the custom configuration is merged with the parent custom configuration of the Component. * @return {Object} custom Component configuration with the specified key. * @public * @deprecated Since 1.27.1. Please use the sap.ui.core.ComponentMetadata#getManifestEntry @@ -644,7 +644,7 @@ sap.ui.define([ * If no key is specified it returns the complete configuration property * * @param {string} [sKey] Key of the configuration property - * @param {boolean} [bDoNotMerge] If set to true, only the local configuration is returned + * @param {boolean} [bDoNotMerge=false] If set to true, only the local configuration is returned * @return {object} the value of the configuration property * @public * @since 1.15.1 diff --git a/src/sap.ui.core/src/sap/ui/core/Element.js b/src/sap.ui.core/src/sap/ui/core/Element.js index bc113ef7961c..1d82df3ef192 100644 --- a/src/sap.ui.core/src/sap/ui/core/Element.js +++ b/src/sap.ui.core/src/sap/ui/core/Element.js @@ -632,7 +632,7 @@ sap.ui.define([ * * @param {object} oDelegate the delegate object * @param {boolean} [bCallBefore=false] if true, the delegate event listeners are called before the event listeners of the element; default is "false". In order to also set bClone, this parameter must be given. - * @param {object} [oThis] if given, this object will be the "this" context in the listener methods; default is the delegate object itself + * @param {object} [oThis=oDelegate] if given, this object will be the "this" context in the listener methods; default is the delegate object itself * @param {boolean} [bClone=false] if true, this delegate will also be attached to any clones of this element; default is "false" * @return {sap.ui.core.Element} Returns this to allow method chaining * @private @@ -733,7 +733,7 @@ sap.ui.define([ * * * @param {object} oDelegate The delegate object which consists of the event handler names and the corresponding event handler functions - * @param {object} [oThis] If given, this object will be the "this" context in the listener methods; default is the delegate object itself + * @param {object} [oThis=oDelegate] If given, this object will be the "this" context in the listener methods; default is the delegate object itself * @returns {sap.ui.core.Element} Returns this to allow method chaining * @since 1.9.0 * @public diff --git a/src/sap.ui.core/src/sap/ui/core/Manifest.js b/src/sap.ui.core/src/sap/ui/core/Manifest.js index 671c647e6d68..ec46d87588bb 100644 --- a/src/sap.ui.core/src/sap/ui/core/Manifest.js +++ b/src/sap.ui.core/src/sap/ui/core/Manifest.js @@ -155,7 +155,7 @@ sap.ui.define([ * flag is set to true, the given terminologies will be respected when replacing placeholders with resource * bundle values. * To use active terminologies, the sap.app.i18n section in the manifest - * must be defined in object syntax as described here: {@link topic:CPOUI5FRAMEWORK-57_Docu_Chapter Text Verticalization}. + * must be defined in object syntax as described here: {@link topic:eba8d25a31ef416ead876e091e67824e Text Verticalization}. * The order of the given active terminologies is significant. The {@link sap.base.i18n.ResourceBundle ResourceBundle} API * documentation describes the processing behavior in more detail. * @@ -825,14 +825,18 @@ sap.ui.define([ * @param {object} mOptions the configuration options * @param {string} mOptions.manifestUrl URL of the manifest * @param {string} [mOptions.componentName] name of the component - * @param {boolean} [mOptions.async] Flag whether to load the manifest async or not (defaults to false) - * @param {boolean} [mOptions.failOnError] Flag whether to fail if an error occurs or not (defaults to true). + * @param {boolean} [mOptions.async=false] Flag whether to load the manifest async or not + * @param {boolean} [mOptions.failOnError=true] Flag whether to fail if an error occurs or not * If set to false, errors during the loading of the manifest.json file (e.g. 404) will be ignored and * the resulting manifest object will be null. * For asynchronous calls the returned Promise will not reject but resolve with null. * @param {function} [mOptions.processJson] Callback for asynchronous processing of the loaded manifest. * The callback receives the parsed manifest object and must return a Promise which resolves with an object. * It allows to early access and modify the manifest object. + * @param {string[]} [mOptions.activeTerminologies] A list of active terminologies. + * The order of the given active terminologies is significant. The {@link sap.base.i18n.ResourceBundle ResourceBundle} API + * documentation describes the processing behavior in more detail. + * Please have a look at this dev-guide chapter for general usage instructions: {@link topic:eba8d25a31ef416ead876e091e67824e Text Verticalization}. * @return {sap.ui.core.Manifest|Promise} Manifest object or for asynchronous calls an ECMA Script 6 Promise object will be returned. * @protected */ diff --git a/src/sap.ui.core/src/sap/ui/core/Popup.js b/src/sap.ui.core/src/sap/ui/core/Popup.js index 764a4504db40..89fa79d1caa9 100644 --- a/src/sap.ui.core/src/sap/ui/core/Popup.js +++ b/src/sap.ui.core/src/sap/ui/core/Popup.js @@ -663,7 +663,7 @@ sap.ui.define([ * * If the Popup's OpenState is different from "CLOSED" (i.e. if the Popup is already open, opening or closing), the call is ignored. * - * @param {int} [iDuration] animation duration in milliseconds; default is the jQuery preset "fast". For iDuration == 0 the opening happens synchronously without animation. + * @param {int} [iDuration=jQuery.fx.speed.fast] animation duration in milliseconds. For iDuration == 0 the opening happens synchronously without animation. * @param {sap.ui.core.Popup.Dock} [my=sap.ui.core.Popup.Dock.CenterCenter] the popup content's reference position for docking * @param {sap.ui.core.Popup.Dock} [at=sap.ui.core.Popup.Dock.CenterCenter] the "of" element's reference point for docking to * @param {string | sap.ui.core.Element | Element | jQuery | jQuery.Event} [of=document] specifies the reference element to which the given content should dock to @@ -1181,7 +1181,7 @@ sap.ui.define([ * If the Popup is in the process of being opened and closed with an animation duration, the animation will be chained, but this functionality is dangerous, * may lead to inconsistent behavior and is thus not recommended and may even be removed. * - * @param {int} [iDuration] animation duration in milliseconds; default is the jQuery preset "fast". For iDuration == 0 the closing happens synchronously without animation. + * @param {int} [iDuration=jQuery.fx.speed.fast] Animation duration in milliseconds. For iDuration == 0 the closing happens synchronously without animation. * @public */ Popup.prototype.close = function(iDuration) { @@ -2129,10 +2129,9 @@ sap.ui.define([ * Sets the durations for opening and closing animations. * Null values and values < 0 are ignored. * A duration of 0 means no animation. - * Default value is "fast" which is the jQuery constant for "200 ms". * - * @param {int} iOpenDuration in milliseconds - * @param {int} iCloseDuration in milliseconds + * @param {int} [iOpenDuration=jQuery.fx.speed.fast] in milliseconds + * @param {int} [iCloseDuration=jQuery.fx.speed.fast] in milliseconds * @return {sap.ui.core.Popup} this to allow method chaining * @public */ diff --git a/src/sap.ui.core/src/sap/ui/core/routing/Router.js b/src/sap.ui.core/src/sap/ui/core/routing/Router.js index 173e670ba894..93ec9120437b 100644 --- a/src/sap.ui.core/src/sap/ui/core/routing/Router.js +++ b/src/sap.ui.core/src/sap/ui/core/routing/Router.js @@ -168,7 +168,7 @@ sap.ui.define([ * } * }); * - * @param {boolean} [oConfig.async=false] @since 1.34. Whether the views which are loaded within this router instance asyncly. The default value is set to false. + * @param {boolean} [oConfig.async=false] @since 1.34. Whether the views which are loaded within this router instance asyncly * @param {sap.ui.core.UIComponent} [oOwner] the Component of all the views that will be created by this Router,
* will get forwarded to the {@link sap.ui.core.routing.Views#constructor}.
* If you are using the componentMetadata to define your routes you should skip this parameter. @@ -194,7 +194,7 @@ sap.ui.define([ * path: "my.application.namespace", * viewType: "XML" * }, - * // You should only use this constructor when you are not using a router with a component. + * // You should only use this constructor when you are using a router without a component. * // Please use the metadata of a component to define your routes and targets. * // The documentation can be found here: {@link sap.ui.core.UIComponent.extend}. * null, diff --git a/src/sap.ui.core/src/sap/ui/core/routing/Targets.js b/src/sap.ui.core/src/sap/ui/core/routing/Targets.js index acfb39578446..27d607764bd5 100644 --- a/src/sap.ui.core/src/sap/ui/core/routing/Targets.js +++ b/src/sap.ui.core/src/sap/ui/core/routing/Targets.js @@ -181,9 +181,8 @@ sap.ui.define([ * * * @param {string} [oOptions.targets.anyName.usage] Defines the 'usage' name for 'Component' target which refers to the '/sap.ui5/componentUsages' entry in the owner component's manifest. - * @param {string} [oOptions.targets.anyName.viewType] - * The type of the view that is going to be created. These are the supported types: {@link sap.ui.core.mvc.ViewType}. - * You always have to provide a viewType except if you are using {@link sap.ui.core.routing.Views#setView}. + * @param {string} [oOptions.targets.anyName.viewType=oOptions.config.viewType] The type of the view that is going to be created. These are the supported types: {@link sap.ui.core.mvc.ViewType}. + * You always have to provide a viewType except if oOptions.config.viewType is set or when using {@link sap.ui.core.routing.Views#setView}. * @param {string} [oOptions.targets.anyName.path] * A prefix that will be prepended in front of the name.
* Example: name is set to "myView" and path is set to "myApp" - the created view name will be "myApp.myView". diff --git a/src/sap.ui.core/src/sap/ui/core/util/Export.js b/src/sap.ui.core/src/sap/ui/core/util/Export.js index 186c80775248..a112eb41c3a1 100644 --- a/src/sap.ui.core/src/sap/ui/core/util/Export.js +++ b/src/sap.ui.core/src/sap/ui/core/util/Export.js @@ -321,7 +321,7 @@ sap.ui.define(['sap/ui/core/Control', './ExportColumn', './ExportRow', './Export * jQuery specific Promise methods ('done', 'fail', 'always', 'pipe' and 'state') are still available but should not be used. * Please use only the standard methods 'then' and 'catch'!

* - * @param {string} [sFileName] file name, defaults to 'data' + * @param {string} [sFileName="data"] The file name * @return {Promise} Promise object * * @public diff --git a/src/sap.ui.core/src/sap/ui/core/util/File.js b/src/sap.ui.core/src/sap/ui/core/util/File.js index 85c8e282765c..02bd6d3473a5 100644 --- a/src/sap.ui.core/src/sap/ui/core/util/File.js +++ b/src/sap.ui.core/src/sap/ui/core/util/File.js @@ -43,7 +43,7 @@ sap.ui.define(["sap/ui/thirdparty/jquery"], * @param {string} sMimeType file mime-type * @param {string} sCharset file charset * @param {boolean} [bByteOrderMark] Whether to prepend a unicode byte order mark (only applies for utf-8 charset). - * Default is false except when sFileExtension = csv it is true (compatibility reasons). + * Default is false except when sFileExtension === 'csv' and sCharset === 'utf-8' it is true (compatibility reasons). * * @public */ diff --git a/src/sap.ui.core/src/sap/ui/core/util/MockServer.js b/src/sap.ui.core/src/sap/ui/core/util/MockServer.js index 382a373b3f93..c850bed9a9b4 100644 --- a/src/sap.ui.core/src/sap/ui/core/util/MockServer.js +++ b/src/sap.ui.core/src/sap/ui/core/util/MockServer.js @@ -1944,8 +1944,8 @@ sap.ui * @param {string} sMetadataString Either the URL to the service metadata document or the metadata document as xml string itself (starting with "undefined, all entity sets will be retrieved. This parameter should be used to improve performance in case there are a lot of entity sets but only a few are needed to be fetched. * * @since 1.13.2 * @public