[INTERNAL] jsdoc plugin: support for @ui5-omissible-params

Used to list the optional @params of a method which can not only be given as undefined, but also omitted (implementation supports shifting of the subsequent parameters). Change-Id: I9722768222f147191490c17186cb44121c8585be
SAP · Jan 20, 2023 · d158351 · d158351
1 parent 03b9165
commit d158351
Show file tree

Hide file tree

Showing 3 changed files with 28 additions and 0 deletions.
diff --git a/lib/jsdoc/schemas/sap-ui-library-api.json b/lib/jsdoc/schemas/sap-ui-library-api.json
@@ -308,6 +308,10 @@
 					"type": "boolean",
 					"defaultValue": false
 				},
+				"omissible": {
+					"type": "boolean",
+					"defaultValue": false
+				},
 				"repeatable": {
 					"type": "boolean",
 					"defaultValue": false

diff --git a/lib/jsdoc/ui5/plugin.js b/lib/jsdoc/ui5/plugin.js
@@ -21,12 +21,18 @@
  *   experimental
  *
  *   final
+ * 
+ *   hideconstructor
  *
  *   interface
  *
  *   implements
  *
+ *   ui5-omissible-param
  *
+ *   ui5-restricted
+ *
+ * 
  *
  * It furthermore listens to the following JSDoc3 events to implement additional functionality
  *
@@ -2594,6 +2600,13 @@ exports.defineTags = function(dictionary) {
 			}
 		}
 	});
+	dictionary.defineTag('ui5-omissible-params', {
+		onTagged: function(doclet, tag) {
+			if ( tag.value ) {
+				ui5data(doclet).omissibleParams = tag.value.trim().split(/\s*,\s*/);
+			}
+		}
+	});
 
 	/**
 	 * Mark a doclet as synthetic.

diff --git a/lib/jsdoc/ui5/template/publish.js b/lib/jsdoc/ui5/template/publish.js
@@ -2856,6 +2856,7 @@ function createAPIJSON4Symbol(symbol, omitDefaults) {
 			}
 		}
 
+		const omissibleParams = new Set(member.__ui5 && member.__ui5.omissibleParams);
 		if ( member.params && member.params.length > 0 ) {
 			collection("parameters");
 			for ( let j = 0; j < member.params.length; j++) {
@@ -2867,6 +2868,13 @@ function createAPIJSON4Symbol(symbol, omitDefaults) {
 				attrib("name", param.name);
 				attrib("type", listTypes(param.type));
 				attrib("optional", !!param.optional, false, /* raw = */true);
+				if ( omissibleParams.has(param.name) ) {
+					if ( !param.optional ) {
+						throw new Error(`@param ${param.name} is specified in '@ui5-omissible-params' for '${member.name}', but not marked as optional. Only optional params can be omissible.`);
+					}
+					attrib("omissible", true, false, /* raw = */true);
+					omissibleParams.delete(param.name);
+				}
 				if ( param.variable ) {
 					attrib("repeatable", !!param.variable, false, /* raw = */true);
 				}
@@ -2882,6 +2890,9 @@ function createAPIJSON4Symbol(symbol, omitDefaults) {
 			}
 			endCollection("parameters");
 		}
+		if ( omissibleParams.size > 0 ) {
+			throw new Error(`parameter(s) '${[...omissibleParams].join("' and '")}' specified as '@ui5-omissible-params' for '${member.name}' missing among the actual @params`);
+		} 
 
 		exceptions(member);