[FEATURE] jsdoc: Improve support for ES6+ syntax (#785)

JIRA: CPOUI5FOUNDATION-374 ### Enabled features: * ArrowFunctions + ArrowFunctionExpression.expression * Avoid "computed" Identifier to be used at it might lead to hidden bugs * Optional Chaining for MemberExpression & CallExpression * Literals for Syntax.OptionalMemberExpression/OptionalCallExpression * Enhance LogicalExpression to support "||" and "??" oprators * Cover ChainExpression * Wrapper Expressions generic approach * Cover possible returning statements in JS * Support alternate definitions of modules * ES6 Class definition export * Support of TemplateLiterals - only withput expression - treated like normal strings
SAP · Sep 9, 2022 · 187a6a3 · 187a6a3
1 parent a6146a5
commit 187a6a3
Show file tree

Hide file tree

Showing 10 changed files with 486 additions and 138 deletions.
diff --git a/lib/processors/jsdoc/lib/ui5/plugin.js b/lib/processors/jsdoc/lib/ui5/plugin.js
diff --git a/test/expected/build/library.j/dest/resources/library/j/dependency-es6-1.js b/test/expected/build/library.j/dest/resources/library/j/dependency-es6-1.js
@@ -0,0 +1,31 @@
+/*!
+ * ${copyright}
+ */
+
+/**
+ * Covers:
+ * - ArrowFunction
+ * - ChainExpression
+ * - ClassDeclaration
+ */
+(sap?.ui).define([`Bar`], (Bar) => {
+	/**
+	 * @class
+	 * My super documentation of this class
+	 *
+	 * @extends library.j.Bar
+	 *
+	 * @author SAP SE
+	 * @version ${version}
+	 *
+	 * @public
+	 * @alias library.j.Foo
+	 */
+	class Foo extends Bar {
+		make() {
+			sap.ui.require("conditional/module1");
+		}
+	}
+
+	return Foo;
+});
diff --git a/test/expected/build/library.j/dest/resources/library/j/dependency-es6-2.js b/test/expected/build/library.j/dest/resources/library/j/dependency-es6-2.js
@@ -0,0 +1,46 @@
+/*!
+ * ${copyright}
+ */
+
+/**
+ * Covers:
+ * - ArrowFunctionExpression
+ */
+window.someRandomModule ||
+	sap.ui.define(
+		["./a"],
+		/**
+		 * Constructor for a new library.j.aaa.
+		 *
+		 * @param {string} [sId] ID for the new control, generated automatically if no ID is given
+		 * @param {object} [mSettings] Initial settings for the new control
+		 *
+		 * @class
+		 *
+		 * @author SAP SE
+		 * @version ${version}
+		 *
+		 * @constructor
+		 * @extends library.j.a
+		 * @public
+		 * @since 1.22
+		 * @alias library.j.aaa
+		 * @ui5-metamodel This control will also be described in the UI5 (legacy) design time meta model.
+		 */
+		(a) =>
+			a.extend(`library.j.aaa`, {
+				metadata: {
+					properties: {
+						/**
+						 * MyProp property
+						 * @since 1.46
+						 */
+						MyProp: {
+							type: "boolean",
+							group: `Misc`,
+							defaultValue: false,
+						},
+					},
+				},
+			})
+	);
diff --git a/test/expected/build/library.j/dest/resources/library/j/dependency-es6-3.js b/test/expected/build/library.j/dest/resources/library/j/dependency-es6-3.js
@@ -0,0 +1,12 @@
+/*!
+ * ${copyright}
+ */
+
+/**
+ * Covers:
+ * - Generators 
+ * - YeldExpression
+ */
+sap.ui.define([], function* someGenerator(genVar) {
+	yield genVar++;
+});
diff --git a/test/expected/build/library.j/dest/resources/library/j/some.js b/test/expected/build/library.j/dest/resources/library/j/some.js
@@ -2,15 +2,19 @@
  * ${copyright}
  */
 
-sap.ui.define([],
-	function() {
-	"use strict";
+sap.ui.define(
+	["./dependency-es6-1"],
+	["./dependency-es6-2"],
+	["./dependency-es6-3"],
+	function (dep1, dep2, dep3) {
+		"use strict";
 
-	/**
-	 * @alias library.j
-	 * @namespace
-	 * @public
-	 */
-	var SomeFunction = function() {};
-
-}, /* bExport= */ true);
+		/**
+		 * @alias library.j
+		 * @namespace
+		 * @public
+		 */
+		var SomeFunction = function () {};
+	},
+	/* bExport= */ true
+);
diff --git a/test/expected/build/library.j/dest/test-resources/library/j/designtime/api.json b/test/expected/build/library.j/dest/test-resources/library/j/designtime/api.json
@@ -1 +1 @@
-{"$schema-ref":"http://schemas.sap.com/sapui5/designtime/api.json/1.0","version":"1.0.0","library":"library.j","symbols":[{"kind":"namespace","name":"library.j","basename":"j","resource":"library/j/some.js","module":"library/j/some","static":true,"visibility":"public"}]}
+{"$schema-ref":"http://schemas.sap.com/sapui5/designtime/api.json/1.0","version":"1.0.0","library":"library.j","symbols":[{"kind":"namespace","name":"library.j","basename":"j","resource":"library/j/some.js","module":"library/j/some","static":true,"visibility":"public"},{"kind":"class","name":"library.j.aaa","basename":"aaa","resource":"library/j/dependency-es6-2.js","module":"library/j/dependency-es6-2","export":"","static":true,"visibility":"public","since":"1.22","extends":"library.j.a","ui5-metamodel":true,"ui5-metadata":{"properties":[{"name":"MyProp","type":"boolean","defaultValue":false,"group":"undefined","visibility":"public","since":"1.46","description":"MyProp property","methods":["getMyProp","setMyProp"]}]},"constructor":{"visibility":"public","parameters":[{"name":"sId","type":"string","optional":true,"description":"ID for the new control, generated automatically if no ID is given"},{"name":"mSettings","type":"object","optional":true,"description":"Initial settings for the new control"}],"description":"Constructor for a new library.j.aaa."},"methods":[{"name":"extend","visibility":"public","static":true,"returnValue":{"type":"function","description":"Created class / constructor function"},"parameters":[{"name":"sClassName","type":"string","optional":false,"description":"Name of the class being created"},{"name":"oClassInfo","type":"object","optional":true,"description":"Object literal with information about the class"},{"name":"FNMetaImpl","type":"function","optional":true,"description":"Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class"}],"description":"Creates a new subclass of class library.j.aaa with name <code>sClassName</code> and enriches it with the information contained in <code>oClassInfo</code>.\n\n<code>oClassInfo</code> might contain the same kind of information as described in {@link library.j.a.extend}."},{"name":"getMetadata","visibility":"public","static":true,"returnValue":{"type":"sap.ui.base.Metadata","description":"Metadata object describing this class"},"description":"Returns a metadata object for class library.j.aaa."},{"name":"getMyProp","visibility":"public","since":"1.46","returnValue":{"type":"boolean","description":"Value of property <code>MyProp</code>"},"description":"Gets current value of property {@link #getMyProp MyProp}.\n\nMyProp property\n\nDefault value is <code>false</code>."},{"name":"setMyProp","visibility":"public","since":"1.46","returnValue":{"type":"this","description":"Reference to <code>this</code> in order to allow method chaining"},"parameters":[{"name":"bMyProp","type":"boolean","optional":true,"defaultValue":false,"description":"New value for property <code>MyProp</code>"}],"description":"Sets a new value for property {@link #getMyProp MyProp}.\n\nMyProp property\n\nWhen called with a value of <code>null</code> or <code>undefined</code>, the default value of the property will be restored.\n\nDefault value is <code>false</code>."}]},{"kind":"class","name":"library.j.Foo","basename":"Foo","resource":"library/j/dependency-es6-1.js","module":"library/j/dependency-es6-1","static":true,"visibility":"public","extends":"library.j.Bar","description":"My super documentation of this class","constructor":{"visibility":"public"}}]}
diff --git a/test/fixtures/library.j/main/src/library/j/dependency-es6-1.js b/test/fixtures/library.j/main/src/library/j/dependency-es6-1.js
@@ -0,0 +1,31 @@
+/*!
+ * ${copyright}
+ */
+
+/**
+ * Covers:
+ * - ArrowFunction
+ * - ChainExpression
+ * - ClassDeclaration
+ */
+(sap?.ui).define([`Bar`], (Bar) => {
+	/**
+	 * @class
+	 * My super documentation of this class
+	 *
+	 * @extends library.j.Bar
+	 *
+	 * @author SAP SE
+	 * @version ${version}
+	 *
+	 * @public
+	 * @alias library.j.Foo
+	 */
+	class Foo extends Bar {
+		make() {
+			sap.ui.require("conditional/module1");
+		}
+	}
+
+	return Foo;
+});
diff --git a/test/fixtures/library.j/main/src/library/j/dependency-es6-2.js b/test/fixtures/library.j/main/src/library/j/dependency-es6-2.js
@@ -0,0 +1,46 @@
+/*!
+ * ${copyright}
+ */
+
+/**
+ * Covers:
+ * - ArrowFunctionExpression
+ */
+window.someRandomModule ||
+	sap.ui.define(
+		["./a"],
+		/**
+		 * Constructor for a new library.j.aaa.
+		 *
+		 * @param {string} [sId] ID for the new control, generated automatically if no ID is given
+		 * @param {object} [mSettings] Initial settings for the new control
+		 *
+		 * @class
+		 *
+		 * @author SAP SE
+		 * @version ${version}
+		 *
+		 * @constructor
+		 * @extends library.j.a
+		 * @public
+		 * @since 1.22
+		 * @alias library.j.aaa
+		 * @ui5-metamodel This control will also be described in the UI5 (legacy) design time meta model.
+		 */
+		(a) =>
+			a.extend(`library.j.aaa`, {
+				metadata: {
+					properties: {
+						/**
+						 * MyProp property
+						 * @since 1.46
+						 */
+						MyProp: {
+							type: "boolean",
+							group: `Misc`,
+							defaultValue: false,
+						},
+					},
+				},
+			})
+	);
diff --git a/test/fixtures/library.j/main/src/library/j/dependency-es6-3.js b/test/fixtures/library.j/main/src/library/j/dependency-es6-3.js
@@ -0,0 +1,12 @@
+/*!
+ * ${copyright}
+ */
+
+/**
+ * Covers:
+ * - Generators 
+ * - YeldExpression
+ */
+sap.ui.define([], function* someGenerator(genVar) {
+	yield genVar++;
+});
diff --git a/test/fixtures/library.j/main/src/library/j/some.js b/test/fixtures/library.j/main/src/library/j/some.js
@@ -2,15 +2,19 @@
  * ${copyright}
  */
 
-sap.ui.define([],
-	function() {
-	"use strict";
+sap.ui.define(
+	["./dependency-es6-1"],
+	["./dependency-es6-2"],
+	["./dependency-es6-3"],
+	function (dep1, dep2, dep3) {
+		"use strict";
 
-	/**
-	 * @alias library.j
-	 * @namespace
-	 * @public
-	 */
-	var SomeFunction = function() {};
-
-}, /* bExport= */ true);
+		/**
+		 * @alias library.j
+		 * @namespace
+		 * @public
+		 */
+		var SomeFunction = function () {};
+	},
+	/* bExport= */ true
+);