[INTERNAL] lib/processors/jsdoc: Entity type visualization improved

Problem:
In the API Reference section, the complex types of entities
[declared in the jsdoc] are not properly displayed and
linked to their composing types.

Solution:
-- Utilize the existing TypeParser in order to parse the
individual simple-types composing a complex type.
-- Render as links only the simple-types that correspond
to UI5 symbols.

Cherry-picked from SAP/openui5@03bb1394d.

Author: codeworrior

lib/processors/jsdoc/lib/transformApiJson.js

@@ -10,6 +10,7 @@
 "use strict";
 const cheerio = require("cheerio");
 const path = require('path');
+const {TypeParser} = require("./ui5/template/utils/typeParser");
 const log = (function() {
 	try {
 		return require("@ui5/logger").getLogger("builder:processors:jsdoc:transformApiJson");
@@ -36,6 +37,7 @@ function normalizeToUI5GlobalNotation(sModuleName){
 	return sModuleName.replace(/\//g, ".");
 }
 
+const typeParser = new TypeParser();
 
 /**
  * Transforms the api.json as created by the JSDoc build into a pre-processed api.json file suitable for the SDK.
@@ -110,15 +112,78 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 		return func;
 	}
 
-	function fnCreateTypesArr(sTypes) {
-		return sTypes.split("|").map(function (sType) {
-			const bLinkEnabled = !isBuiltInType(sType) && possibleUI5Symbol(sType.replace(/\[\]$/, ""));
-			const oTypeInfo = { value: sType };
-			if (bLinkEnabled) {  // default is false, so omit if not required
-				oTypeInfo.linkEnabled = true;
-			}
-			return oTypeInfo;
-		});
+	function isUI5Type(sType) {
+		return !isBuiltInType(sType) && possibleUI5Symbol(sType);
+	}
+
+	/**
+	 * Returns an object with the parsed custom-type information, namely:
+	 * - types: array of the parsed UI5 types inside the given complex type
+	 * - template: the template string with placeholders for the parsed UI5 types
+	 *
+	 * Examples:
+	 *
+	 * - parseUI5Types("sap.ui.core.ID | sap.ui.core.Control") returns
+	 *   {
+	 *     template: "${0} | ${1}",
+	 *     UI5Types: ["sap.ui.core.ID", "sap.ui.core.Control"]
+	 *   }
+	 *
+	 * - parseUI5Types("Array<sap.ui.core.Control>") returns
+	 *    {
+	 *      template: "Array<${0}>",
+	 *      UI5Types: ["sap.ui.core.Control"]
+	 *    }
+	 *
+	 * - parseUI5Types("Array<sap.ui.core.ID|string>") returns
+	 *    {
+	 *      template: "Array<${0} | string>", // built-in types remain unchanged in the template
+	 *      UI5Types: ["sap.ui.core.ID"]
+	 *    }
+	 *
+	 * - parseUI5Types("Object<string, sap.ui.core.Control>") returns
+	 *    {
+	 *      template: "Object<string, ${0}>", // built-in types remain unchanged in the template
+	 *      UI5Types: ["sap.ui.core.Control"]
+	 *    }
+	 *
+	 * - parseUI5Types("string") returns
+	 *    {
+	 *      template: "string" // skip the types array if empty
+	 *    }
+	 *
+	 * - parseUI5Types("sap.ui.core.Control") returns
+	 *    {
+	 *      UI5Types: ["sap.ui.core.Control"] // skip template if its value is "${0}" (default value)
+	 *    }
+	 * @param {string} sComplexType
+	 * @returns {?template: string, ?UI5Types: string[]}
+	 */
+	function parseUI5Types(sComplexType) {
+		let oParsed;
+		try {
+			oParsed = typeParser.parseSimpleTypes(sComplexType, isUI5Type);
+		} catch (e) {
+			log.error("Error parsing type: " + sComplexType);
+			log.error(e);
+			oParsed = { template: sComplexType };
+		}
+
+		const result = {};
+
+		if (oParsed.template !== '${0}') { // default is '${0}', so omit if not required
+			result.template = oParsed.template;
+		}
+
+		if (oParsed.simpleTypes?.length) { // it can be empty if none of the included simple types satisfied the filter function
+			result.UI5Types = oParsed.simpleTypes
+		}
+
+		return result;
+	}
+
+	function includesIgnoreCase(array, string) {
+		return array.some(item => item.toLowerCase() === string.toLowerCase());
 	}
 
 	/**
@@ -132,7 +197,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 		const builtInTypes = formatters._baseTypes;
 
 		// Early return if the type is directly in baseTypes
-		if (builtInTypes.includes(type)) {
+		if (includesIgnoreCase(builtInTypes, type)) {
 			return true;
 		}
 
@@ -193,7 +258,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 	 * @returns {boolean}
 	 */
 	 function possibleUI5Symbol(sName) {
-	 	 const ui5SymbolRegex = /^(module:)?[a-zA-Z][a-zA-Z0-9/.]*[a-zA-Z0-9]$/;
+	 	 const ui5SymbolRegex = /^(module:)?sap[/.][a-zA-Z][a-zA-Z0-9/.$]*[a-zA-Z0-9]$/
 	 	 return ui5SymbolRegex.test(sName);
 	 }
 
@@ -373,7 +438,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 						// Types
 						oParameter.types = [];
 						if (oParameter.type) {
-							oParameter.types = fnCreateTypesArr(oParameter.type);
+							oParameter.typeInfo = parseUI5Types(oParameter.type);
 							// Keep file size in check
 							delete oParameter.type;
 						}
@@ -458,7 +523,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 					// Type
 					if (oSymbol.kind !== "enum") { // enum properties don't have an own type
 						if (oProperty.type) {
-							oProperty.types = fnCreateTypesArr(oProperty.type);
+							oProperty.typeInfo = parseUI5Types(oProperty.type);
 							// Keep file size in check
 							delete oProperty.type;
 						}
@@ -498,7 +563,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 
 						// Type
 						if (oProperty.type) {
-							oProperty.types = fnCreateTypesArr(oProperty.type);
+							oProperty.typeInfo = parseUI5Types(oProperty.type);
 							// Keep file size in check
 							delete oProperty.type;
 						}
@@ -622,8 +687,9 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 					oMeta.specialSettings.forEach(oSetting => {
 
 						// Link Enabled
-						if (!isBuiltInType(oSetting.type)) {
-							oSetting.linkEnabled = true;
+						if (oSetting.type) {
+							oSetting.typeInfo = parseUI5Types(oSetting.type);
+							delete oSetting.type; // Keep file size in check
 						}
 
 						// Description
@@ -682,9 +748,9 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 					if (oEvent.parameters && Array.isArray(oEvent.parameters)) {
 						oEvent.parameters.forEach(oParameter => {
 
-							// Link Enabled
-							if (!isBuiltInType(oParameter.type)) {
-								oParameter.linkEnabled = true;
+							if (oParameter.type) {
+								oParameter.typeInfo = parseUI5Types(oParameter.type);
+								delete oParameter.type; // Keep file size in check
 							}
 
 							// Description
@@ -1153,9 +1219,14 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 			"array",
 			"element",
 			"Element",
+			"HTMLElement",
+			"Node",
+			"Attr",
 			"Date",
 			"DomRef",
+			"jQuery",
 			"jQuery.promise",
+			"jQuery.event",
 			"QUnit.Assert",
 			"object",
 			"Object",
@@ -1174,6 +1245,10 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 			"TouchList",
 			"undefined",
 			"this",
+			"Blob",
+			"RegExp",
+			"void",
+			"ArrayBuffer",
 			"[object Object]"
 		],
 		ANNOTATIONS_LINK: 'http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part3-csdl.html',
@@ -2092,7 +2167,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 
 						// Handle types
 						if (oProperty.type) {
-							oProperty.types = fnCreateTypesArr(oProperty.type);
+							oProperty.typeInfo = parseUI5Types(oProperty.type);
 							// Keep file size in check
 							delete oProperty.type;
 						}
@@ -2124,7 +2199,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 				if (oMethod.parameters) {
 					oMethod.parameters.forEach(function (oParameter) {
 						if (oParameter.type) {
-							oParameter.types = fnCreateTypesArr(oParameter.type);
+							oParameter.typeInfo = parseUI5Types(oParameter.type);
 							// Keep file size in check
 							delete oParameter.type;
 						}
@@ -2145,7 +2220,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 				// Handle return values
 				if (oMethod.returnValue && oMethod.returnValue.type) {
 					// Handle types
-					oMethod.returnValue.types = fnCreateTypesArr(oMethod.returnValue.type);
+					oMethod.returnValue.typeInfo = parseUI5Types(oMethod.returnValue.type);
 				}
 
 			});