[INTERNAL] lib/processors/jsdoc: no duplicate interfaces when JSDoc/Runtime names differ

When the JSDoc name of an interface differs from the UI5 runtime metadata
name, the interface must not be added twice to the api.json.

Cherry-picked from UI5/openui5@934eef745

Author: codeworrior

lib/processors/jsdoc/lib/ui5/plugin.js

@@ -2432,6 +2432,21 @@ function location(doclet) {
 	return " #" + ui5data(doclet).id + "@" + filename + (doclet.meta.lineno != null ? ":" + doclet.meta.lineno : "") + (doclet.synthetic ? "(synthetic)" : "");
 }
 
+/**
+ * Converts a JSDoc name to a UI5 runtime metadata name.
+ *
+ * Basically, global names in dot notation don't require a conversion. Only when the JSDoc name
+ * is a `module:*` name, the prefix is removed and slashes are converted to dots.
+ *
+ * Note: the conversion in the opposite direction is not well-defined as not every dot has to be
+ *       converted to a slash (e.g. not for named exports or subtypes in another module). This
+ *       also implies that two different JSDoc names might map to the same UI5 runtime metadata
+ *       name. API design should avoid such ambiguities.
+ */
+function toRuntimeMetadataName(longname) {
+	return longname?.startsWith("module:") ? longname.slice("module:".length).replace(/\//g, ".") : longname;
+}
+
 // ---- Comment handling ---------------------------------------------------------------------------
 
 // --- comment related functions that depend on the JSdoc version (e.g. on the used parser)
@@ -2966,7 +2981,7 @@ exports.handlers = {
 			// add metadata to class symbols
 			let classInfo = classInfos[doclet.longname];
 			if (classInfo == null && doclet.longname?.startsWith("module:")) {
-				classInfo = classInfos[doclet.longname.slice("module:".length).replace(/\//g, ".")];
+				classInfo = classInfos[toRuntimeMetadataName(doclet.longname)];
 			}
 			if ( classInfo ) {
 				// debug("class data", doclet.longname, "'" + classInfos[doclet.longname].export + "'");
@@ -3000,11 +3015,18 @@ exports.handlers = {
 				// derive interface implementations from UI5 metadata
 				if ( doclet.__ui5.metadata.interfaces && doclet.__ui5.metadata.interfaces.length ) {
 					/* eslint-disable no-loop-func */
-					doclet.__ui5.metadata.interfaces.forEach((intf) => {
+					doclet.__ui5.metadata.interfaces.forEach((rtmIntf) => {
 						doclet.implements = doclet.implements || [];
-						if ( doclet.implements.indexOf(intf) < 0 ) {
-							info(`  @implements ${intf} derived from UI5 metadata (${doclet.longname})`);
-							doclet.implements.push(intf);
+						// add an interface only if no "matching" JSDoc interface is present already
+
+						// TODO if the JSDoc name and runtime metadata name of an interface differ,
+						// this today requires redundant documentation. Ideally, the JSDoc plugin
+						// should handle this and convert the runtime metadata name to the JSDoc name.
+						// Unfortunately, at this processing step here, the necessary information is
+						// not yet available (external APIs are loaded only later).
+						if ( doclet.implements.every((jsdocIntf) => toRuntimeMetadataName(jsdocIntf) !== rtmIntf)) {
+							info(`  @implements ${rtmIntf} derived from UI5 metadata (${doclet.longname})`);
+							doclet.implements.push(rtmIntf);
 						}
 					});
 					/* eslint-enable no-loop-func */
@@ -3014,7 +3036,7 @@ exports.handlers = {
 			// add DataType info to typedef symbols
 			let typeInfo = typeInfos[doclet.longname];
 			if (typeInfo == null && doclet.longname?.startsWith("module:")) {
-				typeInfo = typeInfos[doclet.longname.slice("module:".length).replace(/\//g, ".")];
+				typeInfo = typeInfos[toRuntimeMetadataName(doclet.longname)];
 			}
 			if ( typeInfo ) {
 				doclet.__ui5.stereotype = 'datatype';