[INTERNAL] JSDoc: fix issue with function types and record types

JSDoc reduces function types to the keyword "function", all other
details of the signature (parameters, return type, constructor type) are
lost. This has been reported as
jsdoc/jsdoc#1510 and a fix has been proposed
in jsdoc/jsdoc#1735 .

This change monkey patches JSDoc 3.6.x with the change from the
mentioned PR 1735.

At the same time, a similar problem regarding record types (structures)
is fixed.

Change-Id: I0e8de19cedf13751ff512f6c8900d441a5862435

.repo

@@ -14,6 +14,11 @@
  <copyright>2015-2017 Evgeny Poberezkin</copyright>
  <pattern>../test/sap/ui/integration/demokit/cardExplorer/webapp/thirdparty/ajv/ajv.min.js</pattern>
  </lib>
+ <lib name="jsdoc-3.6.7" displayName="JSDoc 3" version="3.6.7" homepage="https://github.com/jsdoc/jsdoc">
+ <license url="https://github.com/jsdoc/jsdoc/blob/master/LICENSE" type="Apache-2.0" />
+ <copyright>2011-present Michael Mathews [email protected] and the contributors to JSDoc</copyright>
+ <pattern partial="true" otherContent="SAP" explanation="plugin.js is overall written by SAP, but contains code taken from JSDoc 3.6.7 (see the respective comments)">lib/jsdoc/ui5/plugin.js</pattern>
+ </lib>
  </thirdparty>
  </appData>
 

.reuse/dep5

@@ -457,3 +457,10 @@ Copyright: 2015-2017 Evgeny Poberezkin
 License: MIT
 Comment: these files belong to: ajv
 
+Files: lib/jsdoc/ui5/plugin.js
+Copyright:
+ 2009-2021 SAP SE or an SAP affiliate company and OpenUI5 contributors
+ 2011-present Michael Mathews [email protected] and the contributors to JSDoc
+License: Apache-2.0
+Comment: these files contain content from SAP and JSDoc 3: plugin.js is overall written by SAP, but contains code taken from JSDoc 3.6.7 (see the respective comments)
+

THIRDPARTY.txt

@@ -456,6 +456,12 @@ License: MIT
 License Text: https://github.com/SAP/openui5/blob/master/LICENSES/MIT.txt
 Contained in: ../test/sap/ui/integration/demokit/cardExplorer/webapp/thirdparty/ajv/ajv.min.js
 
+Component: JSDoc 3, version: 3.6.7
+Copyright: 2011-present Michael Mathews [email protected] and the contributors to JSDoc
+License: Apache-2.0
+License Text: https://github.com/SAP/openui5/blob/master/LICENSES/Apache-2.0.txt
+Contained in: lib/jsdoc/ui5/plugin.js
+
 
 ALL LICENSE TEXTS:
 ==================

lib/jsdoc/ui5/plugin.js

@@ -1812,7 +1812,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
  "",
  "@param {object}",
  " [oData] An application-specific payload object that will be passed to the event handler along with the event object when firing the event",
- "@param {function}",
+ "@param {function(sap.ui.base.Event):void}",
  " fnFunction The function to be called when the event occurs",
  "@param {object}",
  " [oListener] Context object to call the event handler with. Defaults to this <code>" + oClassInfo.name + "</code> itself",
@@ -1830,7 +1830,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
  "",
  "The passed function and listener object must match the ones used for event registration.",
  "",
- "@param {function}",
+ "@param {function(sap.ui.base.Event):void}",
  " fnFunction The function to be called, when the event occurs",
  "@param {object}",
  " [oListener] Context object on which the given function had to be called",
@@ -2677,3 +2677,107 @@ exports.astNodeVisitor = {
  }
 
 };
+
+(function() {
+ const jsdocType = require("jsdoc/lib/jsdoc/tag/type");
+ const catharsis = require('catharsis');
+ const TYPES = catharsis.Types;
+
+ const toTypeString = (type) => getTypeStrings(type).join("|");
+
+ /*
+ * This function has been copied from jsdoc/lib/jsdoc/tag/type (version 3.6.7)
+ * The copy has been enhanced with the changes from https://github.com/jsdoc/jsdoc/pull/1735
+ * to retain the full function signature for function types.
+ *
+ * JSDoc is copyright (c) 2011-present Michael Mathews [email protected] and the contributors to JSDoc.
+ */ 
+ function getTypeStrings(parsedType, isOutermostType) {
+ let applications;
+ let typeString;
+ let types = [];
+ switch (parsedType.type) {
+ case TYPES.AllLiteral:
+ types.push('*');
+ break;
+ case TYPES.FunctionType:
+ typeString = 'function';
+ // #### BEGIN: MODIFIED BY SAP
+ const paramTypes = [];
+ if (parsedType.new) {
+ paramTypes.push(toTypeString(parsedType.new));
+ }
+ if (Array.isArray(parsedType.params)) {
+ paramTypes.push(...parsedType.params.map(toTypeString));
+ }
+ if (paramTypes.length || parsedType.result) {
+ typeString += `(${paramTypes.join(", ")})`;
+ }
+ if (parsedType.result) {
+ typeString += `:${toTypeString(parsedType.result)}`;
+ }
+ types.push(typeString);
+ // #### END: MODIFIED BY SAP
+ break;
+ case TYPES.NameExpression:
+ types.push(parsedType.name);
+ break;
+ case TYPES.NullLiteral:
+ types.push('null');
+ break;
+ case TYPES.RecordType:
+ // #### BEGIN: MODIFIED BY SAP
+ // types.push('Object');
+ if (Array.isArray(parsedType.fields)) {
+ typeString = `{${parsedType.fields.map(
+ ({key,value}) => `${catharsis.stringify(key)}: ${toTypeString(value)}`
+ ).join(', ')}}`;
+ types.push(typeString);
+ } else {
+ types.push('Object');
+ }
+ // #### END: MODIFIED BY SAP
+ break;
+ case TYPES.TypeApplication:
+ // if this is the outermost type, we strip the modifiers; otherwise, we keep them
+ if (isOutermostType) {
+ applications = parsedType.applications.map(application =>
+ catharsis.stringify(application)).join(', ');
+ typeString = `${getTypeStrings(parsedType.expression)[0]}.<${applications}>`;
+ types.push(typeString);
+ }
+ else {
+ types.push( catharsis.stringify(parsedType) );
+ }
+ break;
+ case TYPES.TypeUnion:
+ parsedType.elements.forEach(element => {
+ types = types.concat( getTypeStrings(element) );
+ });
+ break;
+ case TYPES.UndefinedLiteral:
+ types.push('undefined');
+ break;
+ case TYPES.UnknownLiteral:
+ types.push('?');
+ break;
+ default:
+ // this shouldn't happen
+ throw new Error(`unrecognized type ${parsedType.type} in parsed type: ${parsedType}`);
+ }
+ return types;
+ }
+
+ const origParse = jsdocType.parse;
+ jsdocType.parse = function() {
+ const tagInfo = origParse.apply(this, arguments);
+ if ( tagInfo && /function/.test(tagInfo.typeExpression) && tagInfo.parsedType ) {
+ // console.info("old typeExpression", tagInfo.typeExpression); 
+ // console.info("old parse tree", tagInfo.parsedType); 
+ // console.info("old parse result", tagInfo.type); 
+ tagInfo.type = getTypeStrings(tagInfo.parsedType);
+ // console.info("new parse result", tagInfo.type); 
+ }
+ return tagInfo;
+ }
+}());

src/sap.ui.core/src/sap/ui/core/.library

@@ -233,6 +233,7 @@
  <exclude name="sap.ui.qunit." />
  <exclude name="sap.ui.thirdparty." />
  <exclude name="sap.ui.model.odata.datajs" /> <!-- legacy redirect, only part of internal core overlay -->
+ <exclude name="sap.ui.core.designtime.mvc.ControllerExtensionTemplate" /> <!-- template file with partially unexpected content --> 
  </jsdoc>
  <!-- excludes for the JSCoverage -->
  <jscoverage xmlns="http://www.sap.com/ui5/buildext/jscoverage" >