[INTERNAL] lib/processors/jsdoc: improve indexes for deprecated/exper…

…imental APIs

 - exclude deprecated APIs from the experimental index
 - when a deprecation or experimental flag does not contain a text
   (replacement hint), then don't fall back to the API's description.
 - within a version, sort the deprecated/experimental APIs
   alphabetically (ignoring their case)

Cherry picked from SAP/openui5@57ac8442a

lib/processors/jsdoc/lib/createIndexFiles.cjs

@@ -135,10 +135,11 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
 	function collectLists(oSymbol) {
 
 		function addData(oDataType, oEntityObject, sObjectType, sSymbolName) {
-			let sSince = oDataType !== "since" ? oEntityObject[oDataType].since : oEntityObject.since,
-				oData = {
+			const sSince = oDataType !== "since" ? oEntityObject[oDataType].since : oEntityObject.since;
+			const sText = oDataType !== "since" ? oEntityObject[oDataType].text : oEntityObject.description;
+			const oData = {
 					control: sSymbolName,
-					text: oEntityObject[oDataType].text || oEntityObject.description,
+					text: sText || undefined,
 					type: sObjectType,
 					"static": !!oEntityObject.static,
 					visibility: oEntityObject.visibility
@@ -173,7 +174,7 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
 			addData("deprecated", oSymbol, "class", oSymbol.name);
 		}
 
-		if (oSymbol.experimental) {
+		if (oSymbol.experimental && !oSymbol.deprecated) {
 			addData("experimental", oSymbol, "class", oSymbol.name);
 		}
 
@@ -187,7 +188,7 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
 				addData("deprecated", oMethod, "methods", oSymbol.name);
 			}
 
-			if (oMethod.experimental) {
+			if (oMethod.experimental && !oSymbol.deprecated) {
 				addData("experimental", oMethod, "methods", oSymbol.name);
 			}
 
@@ -202,7 +203,7 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
 				addData("deprecated", oEvent, "events", oSymbol.name);
 			}
 
-			if (oEvent.experimental) {
+			if (oEvent.experimental && !oSymbol.deprecated) {
 				addData("experimental", oEvent, "events", oSymbol.name);
 			}
 
@@ -469,6 +470,17 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
 
 					aKeys.forEach((sKey) => {
 						oSorted[sKey] = oList[sKey];
+						oSorted[sKey].apis.sort((a,b) => {
+							const keyA = `${a.control}|${a.entityName || ""}`.toLowerCase();
+							const keyB = `${b.control}|${b.entityName || ""}`.toLowerCase();
+							if ( keyA === keyB ) {
+								if ( a.static === b.static ) {
+									return 0;
+								}
+								return a.static ? -1 : 1;
+							}
+							return keyA < keyB ? -1 : 1;
+						}); // sort entries within the same version alphabetically (case insensitive)
 					});
 
 					return oSorted;