[FEATURE] Align JSDoc template & plugin with OpenUI5 1.87.0 (#572)

* [FEATURE] Align JSDoc template & plugin with OpenUI5 1.87.0

Includes the following changes

- [INTERNAL] encode property default values as JS string literals
  UI5/openui5@a63d92235

- [INTERNAL] Update copyright year to 2021
  UI5/openui5@bc6825e48

- [FIX] Corrected regular expression (SAPHosted)
  UI5/openui5@319798593

- [FEATURE] Improve documentation for restricted APIs
  UI5/openui5@cb855596b

  - generated "auto-doc" honors visibility of target class. If target
    class is restricted, generated documentation also has visibility
    restricted
  - for restricted APIs, export the list of allowed consumers to
    api.json (property name 'allowedFor')
  - fix split of allowed consumers in tag handler for '@ui5-restricted'
    (comma is the only valid separator)

- [FEATURE] Added FAQ section in ApiRef
  UI5/openui5@8d2d85e69

  An extra FAQ section will be displayed in ApiRef whenever
  FAQ content is specified.

- [INTERNAL] Change to inclusive term "excluded"/"included"
  UI5/openui5@7b2ac1edb

- [INTERNAL] Add missing props to event metadata
  UI5/openui5@ab7ab07ea

  The properties 'allowPreventDefault' and 'enableEventBubbling' had
  been missing in the API summary (api.json) for events.

- [INTERNAL] Make interface validation more robust
  UI5/openui5@32f59b31c

  The validation of an implementation against an implemented interface
  should not crash when the implementation has no methods at all.

- [INTERNAL] Minor improvements of template
  UI5/openui5@e766eeee5

- [INTERNAL] Handling of defaultValues, error logging
  UI5/openui5@3bd509b1f

  A default value of "" (empty string) was not handled properly when
  generating auto-doc comments and a default value of "undefined" was
  not represented in the final api.json.

  To avoid confusion in the log, errors that do not break the build are
  no longer reported as errors, but as 'future errors'.

  APIs that can only be addressed via their global name, not via an AMD
  dependency, can now be marked with @ui5-global-only. They are no
  longer reported as errors during the build (as they can't be fixed).

- [INTERNAL] Export only valid 'since' values
  UI5/openui5@a58310b2d

- [INTERNAL] Normalize notation for generic types
  UI5/openui5@6e4e0ea87

  For generic types, JSDoc allows two different notations, one with a
  dot between the type's name and the type parameters (e.g.
  Array.<string>) and one without the dot. The documentation for the
  Google Closure Compiler (to which JSDoc refers) already rates the
  notation with the dot as 'deprecated' (see
https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System
  , Type Application), JSDoc doesn't.

  However, as the notation without the dot is also common to TypeScript
  developers, all types in the api.json will now be normalized to that
  notation.

- [INTERNAL] Add default value to JSDoc
  UI5/openui5@bb6001950

  Adding default values of function parameters to JSDoc conform notation

* [INTERNAL] Encode property default values as JS string literals

Author: codeworrior

lib/processors/jsdoc/lib/createIndexFiles.js

@@ -1,7 +1,7 @@
 /*
  * Node script to create cross-library API index files for use in the UI5 SDKs.
  *
- * (c) Copyright 2009-2020 SAP SE or an SAP affiliate company.
+ * (c) Copyright 2009-2021 SAP SE or an SAP affiliate company.
  * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
  */
 
@@ -247,7 +247,7 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
 	function convertListToTree(symbols) {
 		let aTree = [];
 
-		// Filter out black list libraries
+		// Filter out excluded libraries
 		symbols = symbols.filter(({lib}) => ["sap.ui.documentation"].indexOf(lib) === -1);
 
 		// Create treeName and displayName

lib/processors/jsdoc/lib/transformApiJson.js

@@ -1,7 +1,7 @@
 /*
  * Node script to preprocess api.json files for use in the UI5 SDKs.
  *
- * (c) Copyright 2009-2020 SAP SE or an SAP affiliate company.
+ * (c) Copyright 2009-2021 SAP SE or an SAP affiliate company.
  * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
  */
 
@@ -35,9 +35,10 @@ const log = (function() {
  * @param {string} sLibraryFile Path to the .library file of the library, used to extract further documentation information
  * @param {string|string[]} vDependencyAPIFiles Path of folder that contains api.json files of predecessor libs or
  *                 an array of paths of those files
+ * @param {string} sFAQDir Path to the directory containing the sources for the FAQ section in APiRef
  * @returns {Promise} A Promise that resolves after the transformation has been completed
  */
-function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles, options) {
+function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles, sFAQDir, options) {
 	const fs = options && options.fs || require("fs");
 	const returnOutputFiles = options && !!options.returnOutputFiles;
 
@@ -46,6 +47,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 	log.info("  output file: " + sOutputFile);
 	log.info("  library file: " + sLibraryFile);
 	log.info("  dependency dir: " + vDependencyAPIFiles);
+	log.info("  FAQ src dir: " + sFAQDir);
 	if (options && options.fs) {
 		log.info("Using custom fs.");
 	}
@@ -785,6 +787,25 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 		})
 	}
 
+	/**
+	 * Check for existence of FAQ data
+	 * (FAQ data must be defined as *.md files in the <code>sFAQDir</code>)
+	 * and add a boolean flag in case it exists
+	 *
+	 * @param oChainObject chain object
+	 */
+	function addFlagsForFAQData(oChainObject) {
+		if (!sFAQDir) {
+			return oChainObject;
+		}
+		oChainObject.fileData.symbols.forEach(function(symbol) {
+			if (fs.existsSync(path.join(sFAQDir, symbol.basename + ".md"))) {
+				symbol.hasFAQ = true;
+			}
+		});
+		return oChainObject;
+	}
+
 	/**
 	 * Create api.json from parsed data
 	 * @param oChainObject chain object
@@ -946,6 +967,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 		_sTopicId: "",
 		_oTopicData: {},
 		_baseTypes: [
+			// TODO this list URGENTLY needs to be replaced by the Type parser and a much smaller list
 			"sap.ui.core.any",
 			"sap.ui.core.object",
 			"sap.ui.core.function",
@@ -969,7 +991,9 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 			"object[]",
 			"object|object[]",
 			"[object Object][]",
+			"Array<[object Object]>",
 			"Array.<[object Object]>",
+			"Object<string,string>",
 			"Object.<string,string>",
 			"function",
 			"float",
@@ -1299,7 +1323,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 
 		handleExternalUrl: function (sTarget, sText) {
 			// Check if the external domain is SAP hosted
-			let bSAPHosted = /^https?:\/\/(?:www.)?[\w.]*(?:sap|hana\.ondemand|sapfioritrial)\.com/.test(sTarget);
+			let bSAPHosted = /^https?:\/\/([\w.]*\.)?(?:sap|hana\.ondemand|sapfioritrial)\.com/.test(sTarget);
 
 			return `<a target="_blank" rel="noopener" href="${sTarget}">${sText}</a>
 <img src="./resources/sap/ui/documentation/sdk/images/${bSAPHosted ? 'link-sap' : 'link-external'}.png"
@@ -2016,6 +2040,7 @@ title="Information published on ${bSAPHosted ? '' : 'non '}SAP site" class="sapU
 		.then(getAPIJSONPromise)
 		.then(loadDependencyLibraryFiles)
 		.then(transformApiJson)
+		.then(addFlagsForFAQData)
 		.then(createApiRefApiJson);
 	return p;