@ui5/builder 4.0.4 → 4.0.6

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

@@ -1,13 +1,11 @@
 /*
  * JSDoc3 plugin for UI5 documentation generation.
  *
- * (c) Copyright 2009-2024 SAP SE or an SAP affiliate company.
+ * (c) Copyright 2025 SAP SE or an SAP affiliate company.
  * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
  */
 
-/* global global, env */
-/* eslint-env es6,node */
-/* eslint strict: [2, "global"] */
+/* global env */
 
 'use strict';
 
@@ -49,8 +47,10 @@
  *   newDoclet
  *
  *   parseComplete
- *     remove undocumented/ignored/private doclets or duplicate doclets
+ *     merge collected class info, DataType info and enum values into doclets
  *
+ *   processingComplete
+ *     remove undocumented/ignored/private doclets or duplicate doclets
  *
  * Last but not least, it implements an astNodeVisitor to detect UI5 specific "extend" calls and to create
  * documentation for the properties, aggregations etc. that are created with the "extend" call.
@@ -189,6 +189,7 @@ const designtimeInfos = Object.create(null);
 /* ---- private functions ---- */
 
 function ui5data(doclet) {
+	// eslint-disable-next-line no-return-assign
 	return doclet.__ui5 || (doclet.__ui5 = { id: ++docletUid });
 }
 
@@ -232,7 +233,7 @@ function resolveModuleName(base, name) {
 	let stack = base.split('/');
 	stack.pop();
 	name.split('/').forEach((segment, i) => {
-		if ( segment == '..' ) {
+		if ( segment === '..' ) {
 			stack.pop();
 		} else if ( segment === '.' ) {
 			// ignore
@@ -283,7 +284,8 @@ function analyzeModuleDefinition(node) {
 				names = [{original: currentModule.factory.params[i].name}];
 			}
 
-			names.forEach(name => {
+			/*eslint-disable no-loop-func */
+			names.forEach((name) => {
 				const module = resolveModuleName(currentModule.module, currentModule.dependencies[i]);
 				debug(`  import ${name.renamed || name.original} from '${module}'`);
 
@@ -292,6 +294,7 @@ function analyzeModuleDefinition(node) {
 					...(name.path ? {path: name.path} : {})
 				};
 			});
+			/*eslint-enable no-loop-func */
 		}
 	}
 	if ( currentModule.factory ) {
@@ -300,11 +303,11 @@ function analyzeModuleDefinition(node) {
 }
 
 /**
- * Searches the given body for variable declarations that can be evaluated statically,
+ * Searches the body of the given factory for variable declarations that can be evaluated statically,
  * either because they refer to known AMD module imports (e.g. shortcut variables)
  * or because they have a (design time) constant value.
  *
- * @param {ASTNode} body AST node of a function body that shall be searched for shortcuts
+ * @param {ASTNode} factory AST node of a factory function whose body that shall be searched for shortcuts
  */
 function collectShortcuts(factory) {
 	const body = factory.body;
@@ -414,12 +417,13 @@ function guessSingularName(sPluralName) {
 
 function getPropertyKey(prop) {
 	if ( prop.type === Syntax.SpreadElement ) {
-		return;
+		return undefined;
 	} else if ( prop.key.type === Syntax.Identifier && prop.computed !== true ) {
 		return prop.key.name;
 	} else if ( prop.key.type === Syntax.Literal ) {
 		return String(prop.key.value);
 	}
+	return undefined;
 }
 
 /**
@@ -456,14 +460,14 @@ function createPropertyMap(node, defaultKey) {
 			return result;
 		}
 
-		if ( node.type != Syntax.ObjectExpression ) {
+		if ( node.type !== Syntax.ObjectExpression ) {
 			// something went wrong, it's not an object literal
 			warning(`not an object literal: ${node.type}: ${node.value}`);
 			// console.log(node.toSource());
 			return undefined;
 		}
 
-		// invariant: node.type == Syntax.ObjectExpression
+		// invariant: node.type === Syntax.ObjectExpression
 		result = {};
 		for (let i = 0; i < node.properties.length; i++) {
 			const prop = node.properties[i];
@@ -478,7 +482,7 @@ function createPropertyMap(node, defaultKey) {
 
 /**
  * Resolves potential wrapper expressions like: ChainExpression, AwaitExpression, etc.
- * @param {Node} node
+ * @param {Node} node the node to unwrap
  * @returns {Node} the resolved node
  */
 function resolvePotentialWrapperExpression(node) {
@@ -495,29 +499,33 @@ function resolvePotentialWrapperExpression(node) {
 					? node.expression.argument
 					: node.expression;
 			}
+			// fall through
 		default:
 			return node;
 	}
 }
 
 /**
- * Strips the ChainExpression wrapper if such
+ * Navigates in the given tree of AST nodes (node) along the given path of property names.
+ * Any reached ChainExpression wrappers are skipped (ignored).
  *
- * @param {Node} rootNode
- * @param {String} path
- * @returns {Node}
+ * @param {Node} rootNode Root of a tree of MemberExpressison nodes
+ * @param {string} path Path to navigate along
+ * @returns {Node} The target node at the end of the path or undefined
  */
 function stripChainWrappers(rootNode, path) {
 	const strip = (node) =>
-		node && node.type === Syntax.ChainExpression ? node.expression : node;
+		(node && node.type === Syntax.ChainExpression ? node.expression : node);
 
 	let curNode = strip(rootNode);
-	let chunks = path && path.split(".");
-	let name;
 
-	while (chunks && chunks.length) {
-		name = chunks.shift();
-		curNode = curNode &&  strip(curNode[name]);
+	if (path) {
+		const chunks = path.split(".");
+
+		while (chunks.length) {
+			const name = chunks.shift();
+			curNode = curNode &&  strip(curNode[name]);
+		}
 	}
 
 	return curNode;
@@ -535,8 +543,8 @@ function isTemplateLiteralWithoutExpression(node) {
 /**
  * Checks whether a node is Literal or TemplateLiteral without an expression
  *
- * @param {Node} node
- * @returns {String}
+ * @param {Node} node AST node to check
+ * @returns {boolean} Whether the given AST node represents a constant string
  */
 function isStringLiteral(node) {
 	return (
@@ -581,10 +589,10 @@ function isArrowFuncExpression(node) {
 }
 
 /**
- * Checks whether the node is of a "returning" type
+ * Checks whether the node is of a "returning" type.
  *
- * @param {Node} node
- * @returns {Boolean}
+ * @param {Node} node A statement node
+ * @returns {boolean} Whether the node is a return stmt or a yield expression statement
  */
 function isReturningNode(node) {
 	return (node && node.type === Syntax.ReturnStatement)
@@ -695,7 +703,7 @@ function resolveObjectPatternChain (valueNode, keyNode, keyChain) {
 		}
 	} else {
 
-		let result = { original: keyNode.name, path: keyChain.join(".") };
+		const result = { original: keyNode.name, path: keyChain.join(".") };
 
 		if (keyNode.name !== valueNode.name) {
 			// Renaming
@@ -712,8 +720,8 @@ function resolveObjectPatternChain (valueNode, keyNode, keyChain) {
  * Tries to resolve an ENUM, regardless where it is defined and being destructured.
  *
  * @param {Node} node
- * @param {String} type
- * @returns {Object}
+ * @param {string} type
+ * @returns {{value:any, raw: any} | undefined}
  */
 function resolvePotentialEnum(node, type) {
 	let value = resolveFullyQuantifiedName(node);
@@ -726,13 +734,14 @@ function resolvePotentialEnum(node, type) {
 			raw: value
 		};
 	}
+	return undefined;
 }
 
 /**
- * Returns the {Node} of the destructured argument of a (arrow) function.
+ * Returns the `Node` of the destructured argument of a (arrow) function.
  *
  * @param {Definition|ParameterDefinition} varDefinition
- * @returns {Node}
+ * @returns {Node | undefined}
  */
 function getFuncArgumentDestructNode(varDefinition) {
 	if (
@@ -745,14 +754,14 @@ function getFuncArgumentDestructNode(varDefinition) {
 		return varDefinition.node.params[varDefinition.index];
 	}
 
-	// return undefined;
+	return undefined;
 }
 
 /**
  * Checks whether a variable has been destructured.
  *
  * @param {Variable} variable
- * @returns
+ * @returns {boolean} whether `variable` uses destructuring.
  */
 function isVarDestructuring(variable) {
 	const defNode =
@@ -761,7 +770,7 @@ function isVarDestructuring(variable) {
 		( getFuncArgumentDestructNode(variable.defs[0]) // (arrow) function argument
 		|| variable.defs[0].node.id ); // variable definition
 
-	return defNode && [Syntax.ObjectPattern, Syntax.ArrayPattern].includes( defNode.type );
+	return defNode != null && [Syntax.ObjectPattern, Syntax.ArrayPattern].includes( defNode.type );
 }
 
 /**
@@ -926,7 +935,7 @@ function getObjectName(node) {
 
 /*
  * Checks whether the node is a qualified name (a.b.c) and if so,
- * returns the leftmost identifier a
+ * returns the leftmost identifier 'a'.
  */
 function getLeftmostName(node) {
 	while ( isMemberExpression(node) ) {
@@ -935,7 +944,7 @@ function getLeftmostName(node) {
 	if ( node.type === Syntax.Identifier ) {
 		return node.name;
 	}
-	// return undefined;
+	return undefined;
 }
 
 function getResolvedObjectName(node) {
@@ -1076,7 +1085,7 @@ function convertValueWithRaw(node, type, propertyName) {
 		}
 
 	} else if ( isTemplateLiteralWithoutExpression(node) ) {
-		let value = node.quasis[0].value || {};
+		const value = node.quasis[0].value || {};
 
 		return {
 			value: value.cooked,
@@ -1145,7 +1154,7 @@ function collectVisibilityInfo(settings, doclet, className, n) {
 	let visibility = (settings.visibility && settings.visibility.value.value) || "public";
 
 	if (!validVisibilities.has(visibility)) {
-		error(`${className}: Invalid visibility '${visibility}' in runtime metadata defined for managed setting '${n}. Valid options are ${Array.from(validVisibilities).join(', ')}.`);
+		error(`${className}: Invalid visibility '${visibility}' in runtime metadata defined for managed setting '${n}'. Valid options are ${Array.from(validVisibilities).join(', ')}.`);
 	}
 
 	if (doclet?.access) {
@@ -1170,7 +1179,7 @@ function collectVisibilityInfo(settings, doclet, className, n) {
 			access = "restricted";
 		}
 
-		if (visibility == "public" && (access === "restricted" || access === "protected")) {
+		if (visibility === "public" && (access === "restricted" || access === "protected")) {
 			visibility = access;
 		}
 	}
@@ -1220,8 +1229,8 @@ function collectClassInfo(extendCall, classDoclet) {
 	function each(node, defaultKey, callback) {
 		const map = node && createPropertyMap(node.value);
 		if ( map ) {
-			for (let n in map ) {
-				if ( map.hasOwnProperty(n) ) {
+			for (const n in map) {
+				if ( Object.hasOwn(map, n) ) {
 					const doclet = getLeadingDoclet(map[n]);
 					const settings = createPropertyMap(map[n].value, defaultKey);
 					if ( settings == null ) {
@@ -1454,8 +1463,8 @@ function collectDesigntimeInfo(dtNodeArgument) {
 	function each(node, defaultKey, callback) {
 		const map = node && createPropertyMap(node.value);
 		if ( map ) {
-			for (let n in map ) {
-				if ( map.hasOwnProperty(n) ) {
+			for (const n in map) {
+				if ( Object.hasOwn(map, n) ) {
 					const doclet = getLeadingDoclet(map[n], true);
 					const settings = createPropertyMap(map[n].value, defaultKey);
 					if ( settings == null ) {
@@ -1645,7 +1654,7 @@ function collectDataTypeInfo(extendCall, classDoclet) {
 					&& stmt.alternate.body[0].argument
 					&& stmt.alternate.body[0].argument.type === Syntax.Literal
 					&& typeof stmt.alternate.body[0].argument.value === 'boolean'
-					&& stmt.consequent.body[0].argument.value !== typeof stmt.alternate.body[0].argument.value ) {
+					&& stmt.consequent.body[0].argument.value !== stmt.alternate.body[0].argument.value ) {
 			const inverse = stmt.alternate.body[0].argument.value;
 			range = determineValueRange(stmt.test, varname, inverse);
 		} else {
@@ -1679,8 +1688,8 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 		if ( !obj ) {
 			return true;
 		}
-		for (let n in obj) {
-			if ( obj.hasOwnProperty(n) ) {
+		for (const n in obj) {
+			if ( Object.hasOwn(obj, n) ) {
 				return false;
 			}
 		}
@@ -1868,8 +1877,8 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 				if ( !isEmpty(oClassInfo.properties) ) {
 					lines.push("<li>Properties");
 					lines.push("<ul>");
-					for (let n in oClassInfo.properties) {
-						lines.push("<li>{@link " + rname("get", n) + " " + n + "} : " + oClassInfo.properties[n].type + (oClassInfo.properties[n].defaultValue !== null && oClassInfo.properties[n].defaultValue.value !== null ? " (default: " + oClassInfo.properties[n].defaultValue.raw + ")" : "") + (oClassInfo.defaultProperty == n ? " (default)" : "") + "</li>");
+					for (const n in oClassInfo.properties) {
+						lines.push("<li>{@link " + rname("get", n) + " " + n + "} : " + oClassInfo.properties[n].type + (oClassInfo.properties[n].defaultValue !== null && oClassInfo.properties[n].defaultValue.value !== null ? " (default: " + oClassInfo.properties[n].defaultValue.raw + ")" : "") + (oClassInfo.defaultProperty === n ? " (default)" : "") + "</li>");
 					}
 					lines.push("</ul>");
 					lines.push("</li>");
@@ -1877,9 +1886,9 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 				if ( !isEmpty(oClassInfo.aggregations) ) {
 					lines.push("<li>Aggregations");
 					lines.push("<ul>");
-					for (let n in oClassInfo.aggregations) {
+					for (const n in oClassInfo.aggregations) {
 						if ( oClassInfo.aggregations[n].visibility !== "hidden" ) {
-							lines.push("<li>{@link " + rname("get", n) + " " + n + "} : " + makeTypeString(oClassInfo.aggregations[n]) + (oClassInfo.defaultAggregation == n ? " (default)" : "") + "</li>");
+							lines.push("<li>{@link " + rname("get", n) + " " + n + "} : " + makeTypeString(oClassInfo.aggregations[n]) + (oClassInfo.defaultAggregation === n ? " (default)" : "") + "</li>");
 						}
 					}
 					lines.push("</ul>");
@@ -1888,7 +1897,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 				if ( !isEmpty(oClassInfo.associations) ) {
 					lines.push("<li>Associations");
 					lines.push("<ul>");
-					for (let n in oClassInfo.associations) {
+					for (const n in oClassInfo.associations) {
 						lines.push("<li>{@link " + rname("get", n) + " " + n + "} : (sap.ui.core.ID | " + oClassInfo.associations[n].type + ")" + (oClassInfo.associations[n].cardinality === "0..n" ? "[]" : "") + "</li>");
 					}
 					lines.push("</ul>");
@@ -1897,7 +1906,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 				if ( !isEmpty(oClassInfo.events) ) {
 					lines.push("<li>Events");
 					lines.push("<ul>");
-					for (let n in oClassInfo.events) {
+					for (const n in oClassInfo.events) {
 						lines.push("<li>{@link " + "#event:" + n + " " + n + "} : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]</li>");
 					}
 					lines.push("</ul>");
@@ -1972,7 +1981,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 		]);
 	}
 
-	for (let n in oClassInfo.properties ) {
+	for (const n in oClassInfo.properties ) {
 		const info = oClassInfo.properties[n];
 		if ( info.visibility === 'hidden' ) {
 			continue;
@@ -2044,7 +2053,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 		}
 	}
 
-	for (let n in oClassInfo.aggregations ) {
+	for (const n in oClassInfo.aggregations ) {
 		const info = oClassInfo.aggregations[n];
 		if ( info.visibility === 'hidden' ) {
 			continue;
@@ -2067,7 +2076,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 			"@name " + name("get", n),
 			"@function"
 		]);
-		if ( info.cardinality == "0..n" ) {
+		if ( info.cardinality === "0..n" ) {
 			const n1 = info.singularName;
 			newJSDoc([
 				"Inserts a " + n1 + " into the aggregation " + link + ".",
@@ -2188,7 +2197,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 		}
 	}
 
-	for (let n in oClassInfo.associations ) {
+	for (const n in oClassInfo.associations ) {
 		const info = oClassInfo.associations[n];
 		if ( info.visibility === 'hidden' ) {
 			continue;
@@ -2262,7 +2271,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 		}
 	}
 
-	for (let n in oClassInfo.events ) {
+	for (const n in oClassInfo.events ) {
 		const info = oClassInfo.events[n];
 		const visibilityTags = createVisibilityTagsForSetting(info, classAccess);
 
@@ -2285,7 +2294,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 			"@param {sap.ui.base.EventProvider} oControlEvent.getSource",
 			"@param {object} oControlEvent.getParameters"
 		];
-		for (let pName in info.parameters ) {
+		for (const pName in info.parameters ) {
 			lines.push(
 				"@param {" + (info.parameters[pName].type || "") + "} oControlEvent.getParameters." + pName + " " + (info.parameters[pName].doc || "")
 			);
@@ -2351,7 +2360,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 			"@param {object} [mParameters] Parameters to pass along with the event"
 		);
 		if ( !isEmpty(info.parameters) ) {
-			for (let pName in info.parameters) {
+			for (const pName in info.parameters) {
 				lines.push(
 					"@param {" + (info.parameters[pName].type || "any") + "} [mParameters." + pName + "] " + (info.parameters[pName].doc || "")
 				);
@@ -2426,6 +2435,7 @@ if ( Syntax.File === 'File' ) {
 				return leadingComments[leadingComments.length - 1];
 			}
 		}
+		return undefined;
 	};
 
 } else {
@@ -2573,7 +2583,7 @@ function preprocessComment(e) {
 // HACK: override cli.exit() to avoid that JSDoc3 exits the VM
 if ( pluginConfig.noExit ) {
 	info("disabling exit() call");
-	require( path.join(global.env.dirname, 'cli') ).exit = function(retval) {
+	require( path.join(env.dirname, 'cli') ).exit = function(retval) {
 		info(`cli.exit(): do nothing (ret val=${retval})`);
 	};
 }
@@ -2915,53 +2925,20 @@ exports.handlers = {
 		currentSource = e.source;
 	},
 
+	/**
+	 * Event `parseComplete` is fired by JSDoc after all files have been parsed,
+	 * but before inheritance, mixins or borrows are processed.
+	 *
+	 * We use this event to merge our additional data into the doclets collected by JSDoc.
+	 * The merge must happen before doclets are cloned during the prcessing of augments or borrows.
+	 */
 	parseComplete : function(e) {
-
 		const doclets = e.doclets;
-		const rAnonymous = /^<anonymous>(~|$)/;
-
-		// remove undocumented symbols, ignored symbols, anonymous functions and their members, scope members
-		let l = doclets.length, i, j;
-		for (i = 0, j = 0; i < l; i++) {
-
-			const doclet = doclets[i];
-			if ( !doclet.undocumented &&
-				!doclet.ignore &&
-				!(doclet.memberof && rAnonymous.test(doclet.memberof)) &&
-				doclet.longname.indexOf("~") < 0 ) {
-				doclets[j++] = doclet;
-			}
-		}
-		if ( j < l ) {
-			doclets.splice(j, l - j);
-			info(`removed ${l - j} undocumented, ignored or anonymous symbols`);
-			l = j;
-		}
-
-		// sort doclets by name, synthetic, lineno, uid
-		// 'ignore' is a combination of criteria, see function above
-		debug("sorting doclets by name");
-		doclets.sort((a, b) => {
-			if ( a.longname === b.longname ) {
-				if ( a.synthetic === b.synthetic ) {
-					if ( a.meta && b.meta && a.meta.filename == b.meta.filename ) {
-						if ( a.meta.lineno !== b.meta.lineno ) {
-							return a.meta.lineno < b.meta.lineno ? -1 : 1;
-						}
-					}
-					return a.__ui5.id - b.__ui5.id;
-				}
-				return a.synthetic && !b.synthetic ? -1 : 1;
-			}
-			return a.longname < b.longname ? -1 : 1;
-		});
-		debug("sorting doclets by name done.");
-
-		for (i = 0, j = 0; i < l; i++) {
-
+		const l = doclets.length;
+		for (let i = 0; i < l; i++) {
 			const doclet = doclets[i];
 
-			// add metadata to symbol
+			// add metadata to class symbols
 			if ( classInfos[doclet.longname] ) {
 				// debug("class data", doclet.longname, "'" + classInfos[doclet.longname].export + "'");
 				if ( doclet.__ui5.export === undefined ) {
@@ -3005,6 +2982,7 @@ exports.handlers = {
 				}
 			}
 
+			// add DataType info to typedef symbols
 			if ( typeInfos[doclet.longname] ) {
 				doclet.__ui5.stereotype = 'datatype';
 				doclet.__ui5.metadata = {
@@ -3014,6 +2992,7 @@ exports.handlers = {
 				};
 			}
 
+			// add enum values to enum keys (for enum symbols)
 			if ( (doclet.kind === 'member' || doclet.kind === 'constant') && doclet.isEnum && Array.isArray(doclet.properties) ) {
 				// determine unique enum identifier from key set
 				let enumID = doclet.properties.map(function(prop) {
@@ -3036,31 +3015,96 @@ exports.handlers = {
 					}
 				}
 			}
+		}
+	},
+
+	/**
+	 * Event `processingComplete` is fired by JSDoc after all files have been parsed,
+	 * and after inheritance, mixins and borrows have been processed.
+	 *
+	 * The `e.doclets` contains the symbols that will be given to templates for publishing.
+	 *
+	 * We use this event to remove symbols that are not of interest:
+	 * - undocumented   When JSDoc finds a class, function, object or member without a
+	 *                  JSDoc comment, it creates a doclet with a truthy `undocumented`
+	 *                  property
+	 * - ignore         A symbol that has been marked with `@ignore` in the source code
+	 * - anonymous      JSDoc could not infer a name for the symbol, neither from source
+	 *                  code nor from JSDoc comments
+	 * - local          Local entities (e.g. local vars) can't be addressed from the outside
+	 *                  and therefore are generally not considered as API in UI5
+	 * - duplicates     This plugin generates doclets for the accessor methods of
+	 *                  managed properties, aggregations, events, associations.
+	 *                  Developers might have created JSDoc comments for the same methods,
+	 *                  either because they have overridden them in code or because they
+	 *                  wanted to detail the method contract. If such duplicate doclets
+	 *                  are detected, the developer created doclets are preferred. If
+	 *                  multiple developer created doclets for the same entity exist in the
+	 *                  same file, the last one wins. If multiple doclets exists across
+	 *                  files, the one created last wins (but usually, this indicates a
+	 *                  copy & paste error)
+	 *
+	 * The cleanup is done in `processingComplete` as the processing of `@augments` or
+	 * `@borrows` tags might have created new non-interesting symbols.
+	 */
+	processingComplete(e) {
+		const doclets = e.doclets;
+
+		// sort doclets by name, synthetic, lineno, uid for easier detection of duplicates
+		debug("sorting doclets by name");
+		doclets.sort((a, b) => {
+			if ( a.longname === b.longname ) {
+				if ( a.synthetic === b.synthetic ) {
+					if ( a.meta && b.meta && a.meta.filename === b.meta.filename ) {
+						if ( a.meta.lineno !== b.meta.lineno ) {
+							return a.meta.lineno < b.meta.lineno ? -1 : 1;
+						}
+					}
+					return a.__ui5.id - b.__ui5.id;
+				}
+				return a.synthetic && !b.synthetic ? -1 : 1;
+			}
+			return a.longname < b.longname ? -1 : 1;
+		});
+		debug("sorting doclets by name done.");
+
+		// cleanup doclets
+		const rAnonymous = /^<anonymous>(~|$)/;
+		const l = doclets.length;
+		let j = 0;
+		for (let i = 0; i < l; i++) {
+			const doclet = doclets[i];
+
+			// skip undocumented, ignored, anonymous entities as well as local entities
+			if (doclet.undocumented
+				|| doclet.ignore
+				|| (doclet.memberof && rAnonymous.test(doclet.memberof))
+				|| doclet.longname.includes("~") ) {
+				continue;
+			}
 
 			// check for duplicates: last one wins
 			if ( j > 0 && doclets[j - 1].longname === doclet.longname ) {
 				if ( !doclets[j - 1].synthetic && !doclet.__ui5.updatedDoclet ) {
-					// replacing synthetic comments or updating comments are trivial case. Just log non-trivial duplicates
+					// replacing synthetic comments or updating comments are trivial cases. Just log non-trivial duplicates
 					debug(`ignoring duplicate doclet for ${doclet.longname}: ${location(doclet)} overrides ${location(doclets[j - 1])}`);
 				}
 				doclets[j - 1] = doclet;
-			} else {
-				doclets[j++] = doclet;
+				continue;
 			}
+
+			doclets[j++] = doclet;
 		}
 
 		if ( j < l ) {
 			doclets.splice(j, l - j);
-			info(`removed ${l - j} duplicate symbols - ${doclets.length} remaining`);
+			info(`processingComplete: removed ${l - j} undocumented, ignored, anonymous, local or duplicate symbols - ${doclets.length} remaining`);
 		}
 
 		if ( pluginConfig.saveSymbols ) {
-
 			fs.mkPath(env.opts.destination);
-			fs.writeFileSync(path.join(env.opts.destination, "symbols-parseComplete.json"), JSON.stringify(e.doclets, null, "\t"), 'utf8');
-
+			fs.writeFileSync(path.join(env.opts.destination, "symbols-processingComplete.json"), JSON.stringify(e.doclets, null, "\t"), 'utf8');
 		}
-
 	}
 };
 
@@ -3122,9 +3166,11 @@ exports.astNodeVisitor = {
 				nodeToAnalyze = node.right;
 			}
 
-			nodeToAnalyze && analyzeModuleDefinition(
-				resolvePotentialWrapperExpression(nodeToAnalyze)
-			);
+			if (nodeToAnalyze) {
+				analyzeModuleDefinition(
+					resolvePotentialWrapperExpression(nodeToAnalyze)
+				);
+			}
 		}
 
 		const isArrowExpression = isArrowFuncExpression(node) && node.body.type === Syntax.ObjectExpression;
@@ -3197,7 +3243,7 @@ exports.astNodeVisitor = {
 
 			let programBodyStart;
 			if ( node.program.body.length >= 1 ) {
-				programBodyStart = node.program.body[0].start
+				programBodyStart = node.program.body[0].start;
 			} else {
 				// File has no code at all
 				programBodyStart = Infinity;
@@ -3236,6 +3282,7 @@ exports.astNodeVisitor = {
 	function getTypeStrings(parsedType, isOutermostType) {
 		let applications;
 		let typeString;
+		let paramTypes;
 		let types = [];
 		switch (parsedType.type) {
 			case TYPES.AllLiteral:
@@ -3244,7 +3291,7 @@ exports.astNodeVisitor = {
 			case TYPES.FunctionType:
 				typeString = 'function';
 				// #### BEGIN: MODIFIED BY SAP
-				const paramTypes = [];
+				paramTypes = [];
 				if (parsedType.new) {
 					paramTypes.push(toTypeString(parsedType.new));
 				}
@@ -3291,7 +3338,7 @@ exports.astNodeVisitor = {
 									const realName = keyString.substring(0, pos);
 									const realValue = keyString.substring(pos + 1, keyString.length);
 									let message = `Cannot parse the "${keyString}" part of "${parsedType.typeExpression}" in RecordType (log output above may give a hint in which file).\n`;
-									message += `Did you mean to specify a property "${realName}" of type "${realValue}"? Then insert a space after the colon and write "${realName}: ${realValue}".`
+									message += `Did you mean to specify a property "${realName}" of type "${realValue}"? Then insert a space after the colon and write "${realName}: ${realValue}".`;
 									error(message);
 									return "x: any"; // unparseable property set to "any" - but the JSDoc run will fail now, anyway
 								} else {
@@ -3310,17 +3357,16 @@ exports.astNodeVisitor = {
 			case TYPES.TypeApplication:
 				// if this is the outermost type, we strip the modifiers; otherwise, we keep them
 				if (isOutermostType) {
-					applications = parsedType.applications.map(application =>
+					applications = parsedType.applications.map((application) =>
 						catharsis.stringify(application)).join(', ');
 					typeString = `${getTypeStrings(parsedType.expression)[0]}.<${applications}>`;
 					types.push(typeString);
-				}
-				else {
+				} else {
 					types.push( catharsis.stringify(parsedType) );
 				}
 				break;
 			case TYPES.TypeUnion:
-				parsedType.elements.forEach(element => {
+				parsedType.elements.forEach((element) => {
 					types = types.concat( getTypeStrings(element) );
 				});
 				break;
@@ -3350,5 +3396,5 @@ exports.astNodeVisitor = {
 			// console.info("new parse result", tagInfo.type);
 		}
 		return tagInfo;
-	}
+	};
 }());