@ui5/builder 5.0.0-alpha.3 → 5.0.0-alpha.4

package/CHANGELOG.md

@@ -4,6 +4,33 @@ This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html
 
 A list of unreleased changes can be found [here](https://github.com/SAP/ui5-builder/compare/v4.0.11...HEAD).
 
+## [5.0.0-alpha.4](https://github.com/UI5/cli/compare/builder-v5.0.0-alpha.3...builder-v5.0.0-alpha.4) (2026-03-24)
+
+
+### Features
+
+* **builder:** Add dynamic section for API reference during JSDoc build ([47970f7](https://github.com/UI5/cli/commit/47970f74c4adf63625e4f330f19090083f563f82))
+* **builder:** Add hierarchical subsection support for API reference sections ([49a3ef5](https://github.com/UI5/cli/commit/49a3ef569074ff84b5f6dfc2cfc619cd1654c2c8))
+* **builder:** Automatically add [@lends](https://github.com/lends) tag to extend calls during JSdoc build ([3547f42](https://github.com/UI5/cli/commit/3547f425b33663f7e5e2618a6d876fe018058d99))
+* **builder:** In JSDoc build, push the deprecation of namespaces down to the contained APIs ([71c08f2](https://github.com/UI5/cli/commit/71c08f2bb1d2cfee34ab9ca2e9e6042b5e67ae0c))
+* **builder:** Mark cross-references to typedefs in the api.json (SDK variant) ([a474700](https://github.com/UI5/cli/commit/a47470050e804192bfab857f6c224faa6e445e10))
+
+
+### Bug Fixes
+
+* **builder:** Improve JSDoc support for "module:" syntax ([aca05f0](https://github.com/UI5/cli/commit/aca05f0b75561f33842ccb30248ede3a82f2ae46))
+* **builder:** JSDoc: avoid errors when symbol has no events ([6e517e6](https://github.com/UI5/cli/commit/6e517e6c7f480784b93e37e94dcf74e0a689427f))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @ui5/fs bumped from ^5.0.0-alpha.3 to ^5.0.0-alpha.4
+    * @ui5/logger bumped from ^5.0.0-alpha.3 to ^5.0.0-alpha.4
+  * devDependencies
+    * @ui5/project bumped from ^5.0.0-alpha.3 to ^5.0.0-alpha.4
+
 ## [5.0.0-alpha.3](https://github.com/UI5/cli/compare/builder-v5.0.0-alpha.2...builder-v5.0.0-alpha.3) (2026-02-13)
 
 

package/lib/processors/bundlers/moduleBundler.js

@@ -58,7 +58,7 @@ const log = getLogger("builder:processors:bundlers:moduleBundler");
  * 		Excludes should be marked with a leading exclamation mark '!'. The order of filters is relevant; a later
  *		exclusion overrides an earlier inclusion, and vice versa.
  *
- * <caption>List of modules as glob patterns that should be in- or excluded</caption>
+ * <i>Example:</i>
  *
  * ```js
  * // Includes everything from "some/path/to/module/",

package/lib/processors/jsdoc/lib/transformApiJson.js

@@ -47,10 +47,10 @@ const typeParser = new TypeParser();
  * @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
+ * @param {string} sSectionsDir Path to the directory containing the sources for the sections (FAQ, documentation, etc.) in the API Reference
  * @returns {Promise} A Promise that resolves after the transformation has been completed
  */
-function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles, sFAQDir, options) {
+function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles, sSectionsDir, options) {
 	const fs = options && options.fs || require("fs");
 	const returnOutputFiles = options && !!options.returnOutputFiles;
 
@@ -59,7 +59,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);
+	log.info("  sections src dir: " + sSectionsDir);
 	if (options && options.fs) {
 		log.info("Using custom fs.");
 	}
@@ -156,9 +156,10 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 	 *      UI5Types: ["sap.ui.core.Control"] // skip template if its value is "${0}" (default value)
 	 *    }
 	 * @param {string} sComplexType
+	 * @param {Object<string,object>} oAllDependentAPIs Map of entity names to their symbol
 	 * @returns {{template=: string, UI5Types=: string[]}}
 	 */
-	function parseUI5Types(sComplexType) {
+	function parseUI5Types(sComplexType, oAllDependentAPIs) {
 		let oParsed;
 		try {
 			oParsed = typeParser.parseSimpleTypes(sComplexType, isUI5Type);
@@ -176,6 +177,14 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 
 		if (oParsed.simpleTypes?.length) { // it can be empty if none of the included simple types satisfied the filter function
 			result.UI5Types = oParsed.simpleTypes;
+
+			// check whether the type refers to a typedef and set a marker
+			if (result.template == null && result.UI5Types.length === 1) {
+				const symbol = oAllDependentAPIs[result.UI5Types[0]];
+				if (symbol?.kind === "typedef" && Array.isArray(symbol.properties)) {
+					result.refersToTypedef = true;
+				}
+			}
 		}
 
 		return result;
@@ -266,6 +275,8 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 	 * @param {object} oChainObject chain object
 	 */
 	const transformApiJson = function (oChainObject) {
+		const {oAllDependentAPIs} = oChainObject;
+
 		// Function is a copy from: LibraryInfo.js => LibraryInfo.prototype._getActualComponent => "match" inline method
 		function matchComponent(sModuleName, sPattern) {
 			sModuleName = sModuleName.toLowerCase();
@@ -435,7 +446,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 						// Types
 						oParameter.types = [];
 						if (oParameter.type) {
-							oParameter.typeInfo = parseUI5Types(oParameter.type);
+							oParameter.typeInfo = parseUI5Types(oParameter.type, oAllDependentAPIs);
 							// Keep file size in check
 							delete oParameter.type;
 						}
@@ -520,7 +531,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 					// Type
 					if (oSymbol.kind !== "enum") { // enum properties don't have an own type
 						if (oProperty.type) {
-							oProperty.typeInfo = parseUI5Types(oProperty.type);
+							oProperty.typeInfo = parseUI5Types(oProperty.type, oAllDependentAPIs);
 							// Keep file size in check
 							delete oProperty.type;
 						}
@@ -560,7 +571,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 
 						// Type
 						if (oProperty.type) {
-							oProperty.typeInfo = parseUI5Types(oProperty.type);
+							oProperty.typeInfo = parseUI5Types(oProperty.type, oAllDependentAPIs);
 							// Keep file size in check
 							delete oProperty.type;
 						}
@@ -657,7 +668,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 							Object.keys(aParams).forEach((sParam) => {
 								const sSince = aParams[sParam].since;
 								const oDeprecated = aParams[sParam].deprecated;
-								const oEvtInSymbol = oSymbol.events.find((e) => e.name === oEvent.name);
+								const oEvtInSymbol = oSymbol.events?.find((e) => e.name === oEvent.name);
 								const oParamInSymbol = oEvtInSymbol && oEvtInSymbol.parameters[0] &&
 														oEvtInSymbol.parameters[0].parameterProperties &&
 														oEvtInSymbol.parameters[0].parameterProperties.getParameters &&
@@ -687,7 +698,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 
 						// Link Enabled
 						if (oSetting.type) {
-							oSetting.typeInfo = parseUI5Types(oSetting.type);
+							oSetting.typeInfo = parseUI5Types(oSetting.type, oAllDependentAPIs);
 							delete oSetting.type; // Keep file size in check
 						}
 
@@ -756,7 +767,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 						oEvent.parameters.forEach((oParameter) => {
 
 							if (oParameter.type) {
-								oParameter.typeInfo = parseUI5Types(oParameter.type);
+								oParameter.typeInfo = parseUI5Types(oParameter.type, oAllDependentAPIs);
 								delete oParameter.type; // Keep file size in check
 							}
 
@@ -789,7 +800,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 			if (oSymbol.methods) {
 
 				// Pre-process methods
-				methods.buildMethodsModel(oSymbol.methods);
+				methods.buildMethodsModel(oSymbol.methods, oAllDependentAPIs);
 
 				oSymbol.methods.forEach((oMethod) => {
 
@@ -950,6 +961,14 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 	}
 
 	function loadDependencyLibraryFiles (oChainObject) {
+		const oAllDependentAPIs = oChainObject.oAllDependentAPIs = Object.create(null);
+		// add symbols from current library
+		if (oChainObject.fileData.symbols) {
+			for (const oSymbol of oChainObject.fileData.symbols) {
+				oAllDependentAPIs[oSymbol.name] = oSymbol;
+			}
+		}
+
 		if (!oChainObject.aDependentLibraryFiles) {
 			return oChainObject;
 		}
@@ -978,6 +997,12 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 				// In this case we don't add it to the dependency list to skip double iteration.
 				if (oData && oChainObject.fileData.library !== oData.library) {
 					oDependentAPIs[oData.library] = oData.symbols;
+
+					if (Array.isArray(oData.symbols)) {
+						for (const oSymbol of oData.symbols) {
+							oAllDependentAPIs[oSymbol.name] = oSymbol;
+						}
+					}
 				}
 			});
 
@@ -987,22 +1012,69 @@ 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>)
+	 * Check for existence of sections data
+	 * (Sections data must be defined as *.md files in the <code>sSectionsDir</code>)
 	 * and add a boolean flag in case it exists
 	 *
 	 * @param oChainObject chain object
 	 */
-	function addFlagsForFAQData(oChainObject) {
-		if (!sFAQDir) {
+	function addFlagsForSectionsData(oChainObject) {
+		if (!sSectionsDir) {
 			return oChainObject;
 		}
+
 		const slibName = oChainObject.fileData.library;
+
 		oChainObject.fileData.symbols.forEach(function(symbol) {
-			const sfile = symbol.name.replace(slibName, "").replace(/[.]/g, "/") + ".md";
-			if (fs.existsSync(path.join(sFAQDir, sfile))) {
-				symbol.hasFAQ = true;
+			const sComponentPath = symbol.name.replace(slibName, "").replace(/^[.]/, "").replace(/[.]/g, "/");
+			if (!sComponentPath) {
+				return;
 			}
+
+			const componentDir = path.join(sSectionsDir, sComponentPath);
+			if (fs.existsSync(componentDir)) {
+				try {
+				const dirContents = fs.readdirSync(componentDir, { withFileTypes: true });
+
+				// Separate files and directories in one pass
+				const mdFiles = [];
+				const dirNames = new Set();
+				dirContents.forEach((dirent) => {
+					if (dirent.isFile() && dirent.name.endsWith('.md')) {
+						mdFiles.push(dirent.name.replace(/\.md$/, ''));
+					} else if (dirent.isDirectory()) {
+						dirNames.add(dirent.name);
+					}
+				});
+
+				// Build customSections array with subsection support
+				const customSections = mdFiles.map(function(sectionName) {
+					// Check if there's a matching directory for this section
+					if (dirNames.has(sectionName)) {
+						try {
+							const subsectionFiles = fs.readdirSync(path.join(componentDir, sectionName), { withFileTypes: true })
+								.filter((dirent) => dirent.isFile() && dirent.name.endsWith('.md'))
+								.map((dirent) => dirent.name.replace(/\.md$/, ''));
+
+							if (subsectionFiles.length > 0) {
+								return { name: sectionName, hasSubsections: true, subsections: subsectionFiles };
+							}
+						} catch (error) {
+							log.error('Error scanning subsection directory:', path.join(componentDir, sectionName), error);
+						}
+					}
+					return sectionName;
+				});
+
+				if (customSections.length > 0) {
+					symbol.customSections = customSections;
+				}
+
+				} catch (error) {
+					log.error('Error scanning component sections directory:', componentDir, error);
+				}
+			}
+
 		});
 		return oChainObject;
 	}
@@ -2175,7 +2247,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 		 * Adjusts methods info so that it can be easily displayed in a table
 		 * @param aMethods - the methods array initially coming from the server
 		 */
-		buildMethodsModel: function (aMethods) {
+		buildMethodsModel: function (aMethods, oAllDependentAPIs) {
 			var fnExtractParameterProperties = function (oParameter, aParameters, iDepth, aPhoneName) {
 				if (oParameter.parameterProperties) {
 					Object.keys(oParameter.parameterProperties).forEach(function (sProperty) {
@@ -2185,7 +2257,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 
 						// Handle types
 						if (oProperty.type) {
-							oProperty.typeInfo = parseUI5Types(oProperty.type);
+							oProperty.typeInfo = parseUI5Types(oProperty.type, oAllDependentAPIs);
 							// Keep file size in check
 							delete oProperty.type;
 						}
@@ -2217,7 +2289,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 				if (oMethod.parameters) {
 					oMethod.parameters.forEach(function (oParameter) {
 						if (oParameter.type) {
-							oParameter.typeInfo = parseUI5Types(oParameter.type);
+							oParameter.typeInfo = parseUI5Types(oParameter.type, oAllDependentAPIs);
 							// Keep file size in check
 							delete oParameter.type;
 						}
@@ -2238,7 +2310,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 				// Handle return values
 				if (oMethod.returnValue && oMethod.returnValue.type) {
 					// Handle types
-					oMethod.returnValue.typeInfo = parseUI5Types(oMethod.returnValue.type);
+					oMethod.returnValue.typeInfo = parseUI5Types(oMethod.returnValue.type, oAllDependentAPIs);
 				}
 
 			});
@@ -2375,6 +2447,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 		inputFile: sInputFile,
 		outputFile: sOutputFile,
 		libraryFile: sLibraryFile,
+		sectionsDir: sSectionsDir,
 		aDependentLibraryFiles: Array.isArray(vDependencyAPIFiles) ? vDependencyAPIFiles : null
 	};
 
@@ -2387,7 +2460,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 		.then(getAPIJSONPromise)
 		.then(loadDependencyLibraryFiles)
 		.then(transformApiJson)
-		.then(addFlagsForFAQData)
+		.then(addFlagsForSectionsData)
 		.then(createApiRefApiJson);
 	return p;
 

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

@@ -73,7 +73,8 @@ const path = require('jsdoc/path');
 const logger = require('jsdoc/util/logger');
 const pluginConfig = (env.conf && env.conf.templates && env.conf.templates.ui5) || env.opts.sapui5 || {};
 const escope = require("escope");
-const {isSemVer} = require("./template/utils/versionUtil");
+const templatePath = path.getResourcePath(env.opts.template) || "./template";
+const {isSemVer} = require(`${templatePath}/utils/versionUtil`);
 
 /* ---- logging ---- */
 
@@ -1220,11 +1221,13 @@ function collectClassInfo(extendCall, classDoclet) {
 	if ( classDoclet && classDoclet.augments && classDoclet.augments.length === 1 ) {
 		baseType = classDoclet.augments[0];
 	}
+	const jsdocClassName = classDoclet?.kind === "class" ? classDoclet.alias || classDoclet.longname : undefined;
+
 	if ( isMemberExpression(extendCall.callee) ) {
 		const baseCandidate = getResolvedObjectName(extendCall.callee.object);
 		if ( baseCandidate && baseType == null ) {
 			baseType = baseCandidate;
-		} else if ( baseCandidate !== baseType ) {
+		} else if ( baseCandidate !== toRuntimeMetadataName(baseType) ) {
 			future(`documented base type '${baseType}' doesn't match technical base type '${baseCandidate}'`);
 		}
 	}
@@ -1283,6 +1286,32 @@ function collectClassInfo(extendCall, classDoclet) {
 	}
 
 	const classInfoNode = extendCall.arguments[1];
+	if (classInfoNode?.type === Syntax.ObjectExpression && jsdocClassName && addLeadingCommentNode) {
+		// Take care of the @lends comment only
+		// - when the class info is an object literal (otherwise lends makes no sense)
+		// - when a class name is found (it might differ from the runtime metadata name)
+		// - when the entity is documented as a class (or else '.prototype' would be wrong)
+		const classInfoComment = getLeadingCommentNode(classInfoNode);
+		if (classInfoComment == null) {
+			// If the class info object doesn't have a @lends tag, add it
+			const raw = `/** @lends ${jsdocClassName}.prototype */`;
+			info(`lends comment injected for class '${jsdocClassName}'`);
+			addLeadingCommentNode(classInfoNode, {
+				type: "CommentBlock",
+				raw,
+				value: raw.slice(2,-2),
+				loc: classInfoNode.loc
+			});
+		} else {
+			// Otherwise check whether the name matches the name of the described class
+			const doclet = new Doclet(getRawComment(classInfoComment), {});
+			// The name after the @lends is surprisingly stored in the 'alias' property
+			if (doclet.alias !== `${jsdocClassName}.prototype`) {
+				future(`lends comment '${doclet.alias}' doesn't match documented class name '${jsdocClassName}'`);
+			}
+		}
+	}
+
 	const classInfoMap = createPropertyMap(classInfoNode);
 	if ( classInfoMap && classInfoMap.metadata && classInfoMap.metadata.value.type !== Syntax.ObjectExpression ) {
 		warning(`class metadata exists but can't be analyzed. It is not of type 'ObjectExpression', but a '${classInfoMap.metadata.value.type}'.`);
@@ -1772,7 +1801,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 	}
 
 	function name(prefix, n, _static) {
-		return oClassInfo.name + rname(prefix, n, _static);
+		return jsdocClassName + rname(prefix, n, _static);
 	}
 
 	/*
@@ -1884,6 +1913,18 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 	const p = m ? m.index : -1;
 	const hasSettingsDocs = rawClassComment.indexOf("The supported settings are:") >= 0;
 	const classAccess = doclet?.access ?? "public";
+
+	// If doclet exists and has an alias or longname, use that when building the fully qualified
+	// names of methods or events.
+	// Do this only when the doclet is of kind "class". Many TypeScript classes unfortunately
+	// use a broken pattern with @namespace (needs to be deprecated in babel-plugin-transform-modules-ui5)
+	const jsdocClassName =
+		(doclet?.kind === "class" ? doclet.alias || doclet.longname : undefined) || oClassInfo.name;
+	if (jsdocClassName !== oClassInfo.name) {
+		info("jsdoc class name differs from runtime metadata name", jsdocClassName, oClassInfo.name);
+	}
+
+	const displayClassName = oClassInfo.name;
 	const visibility = createVisibilityTags(classAccess, doclet?.__ui5?.stakeholders);
 	const thisClass = 'this'; // oClassInfo.name
 
@@ -2007,7 +2048,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 	}
 
 	newJSDoc([
-		"Returns a metadata object for class " + oClassInfo.name + ".",
+		"Returns a metadata object for class " + displayClassName + ".",
 		"",
 		"@returns {sap.ui.base.Metadata} Metadata object describing this class",
 		visibility,
@@ -2018,7 +2059,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 
 	if ( !oClassInfo["final"] ) {
 		newJSDoc([
-			"Creates a new subclass of class " + oClassInfo.name + " with name <code>sClassName</code>",
+			"Creates a new subclass of class " + displayClassName + " with name <code>sClassName</code>",
 			"and enriches it with the information contained in <code>oClassInfo</code>.",
 			"",
 			"<code>oClassInfo</code> might contain the same kind of information as described in {@link " + (oClassInfo.baseType ? oClassInfo.baseType + ".extend" : "sap.ui.base.Object.extend Object.extend") + "}.",
@@ -2304,7 +2345,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 			"",
 			info.enableEventBubbling ? "This event bubbles up the control hierarchy." : "",
 			"",
-			"@name " + oClassInfo.name + "#" + n,
+			"@name " + jsdocClassName + "#" + n,
 			"@event",
 			devStateTags,
 			"@param {sap.ui.base.Event} oControlEvent",
@@ -2321,10 +2362,10 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 		newJSDoc(lines);
 
 		newJSDoc([
-			"Attaches event handler <code>fnFunction</code> to the " + link + " event of this <code>" + oClassInfo.name + "</code>.",
+			"Attaches event handler <code>fnFunction</code> to the " + link + " event of this <code>" + displayClassName + "</code>.",
 			"",
 			"When called, the context of the event handler (its <code>this</code>) will be bound to <code>oListener</code> if specified, ",
-			"otherwise it will be bound to this <code>" + oClassInfo.name + "</code> itself.",
+			"otherwise it will be bound to this <code>" + displayClassName + "</code> itself.",
 			"",
 			!newStyle && info.doc ? info.doc : "",
 			"",
@@ -2333,7 +2374,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 			"@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",
+			"           [oListener] Context object to call the event handler with. Defaults to this <code>" + displayClassName + "</code> itself",
 			"",
 			"@returns {" + thisClass + "} Reference to <code>this</code> in order to allow method chaining",
 			devStateTags,
@@ -2342,7 +2383,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 			"@function"
 		]);
 		newJSDoc([
-			"Detaches event handler <code>fnFunction</code> from the " + link + " event of this <code>" + oClassInfo.name + "</code>.",
+			"Detaches event handler <code>fnFunction</code> from the " + link + " event of this <code>" + displayClassName + "</code>.",
 			"",
 			"The passed function and listener object must match the ones used for event registration.",
 			"",
@@ -2439,6 +2480,7 @@ function toRuntimeMetadataName(longname) {
 
 let isDocComment;
 let getLeadingCommentNode;
+let addLeadingCommentNode;
 
 // JSDoc added the node type <code>Syntax.File</code> with the same change that activated Babylon
 // See https://github.com/jsdoc3/jsdoc/commit/ffec4a42291de6d68e6240f304b68d6abb82a869
@@ -2464,6 +2506,15 @@ if ( Syntax.File === 'File' ) {
 		return undefined;
 	};
 
+	addLeadingCommentNode = function(node, comment) {
+		node.leadingComments ??= [];
+		let index = node.leadingComments.length;
+		while (index > 0 && node.leadingComments[index - 1].type !== 'CommentBlock') {
+			index--;
+		}
+		node.leadingComments.splice(index, 0, comment);
+	}
+
 } else {
 
 	// JSDoc versions before 3.5.0
@@ -2498,6 +2549,9 @@ if ( Syntax.File === 'File' ) {
 
 		return comment;
 	};
+
+	// not implemented for espree (no automatic injection of @lends comments)
+	addLeadingCommentNode = undefined;
 }
 
 //--- comment related functions that are independent from the JSdoc version

package/lib/processors/jsdoc/lib/ui5/template/publish.js

@@ -231,6 +231,7 @@ function publish(symbolSet) {
 
 	// now resolve relationships
 	const aRootNamespaces = createNamespaceTree(allSymbols);
+	pushDownDeprecations(allSymbols);
 	createInheritanceTree(allSymbols);
 	collectMembers(allSymbols);
 	mergeEventDocumentation(allSymbols);
@@ -374,6 +375,33 @@ function makeNamespace(memberof) {
 	]);
 }
 
+function pushDownDeprecations() {
+
+	function pushDown(oSymbol, sInheritedDeprecation) {
+		if (oSymbol == null || !isFirstClassSymbol(oSymbol)) {
+			return;
+		}
+		const sOwnDeprecation = oSymbol.deprecated;
+		if (sOwnDeprecation == null && sInheritedDeprecation != null) {
+			oSymbol.deprecated = sInheritedDeprecation;
+			info(`mark ${oSymbol.longname} as deprecated (${sInheritedDeprecation})`);
+		} else if (sOwnDeprecation != null) {
+			const info = extractSince(sOwnDeprecation);
+			const sinceBecause = info.since ? `As of version ${info.since}, because`: `Because`;
+			sInheritedDeprecation = `${sinceBecause} it is part of the deprecated package ${oSymbol.longname}`;
+		}
+		oSymbol.__ui5.children?.forEach((oChild) => pushDown(oChild, sInheritedDeprecation));
+	}
+
+	// w/o a library name we can't start with the library namespace
+	if (!templateConf.uilib) {
+		return;
+	}
+
+	// start the push down at the library namespace to ensure locality
+	pushDown(lookup(templateConf.uilib));
+}
+
 //---- inheritance hierarchy ----------------------------------------------------------------------------
 
 /*

package/lib/tasks/generateResourcesJson.js

@@ -55,7 +55,7 @@ function getCreatorOptions(projectName) {
  * Therefore it is also not supported in combination with self-contained build.
  * </p>
  *
- * <caption>sample resources.json</caption>
+ * <i>sample resources.json</i>
  *
  * ```js
  * const resourcesJson = {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ui5/builder",
-	"version": "5.0.0-alpha.3",
+	"version": "5.0.0-alpha.4",
 	"description": "UI5 CLI - Builder",
 	"author": {
 		"name": "SAP SE",
@@ -91,8 +91,8 @@
 	},
 	"dependencies": {
 		"@jridgewell/sourcemap-codec": "^1.5.5",
-		"@ui5/fs": "^5.0.0-alpha.3",
-		"@ui5/logger": "^5.0.0-alpha.3",
+		"@ui5/fs": "^5.0.0-alpha.4",
+		"@ui5/logger": "^5.0.0-alpha.4",
 		"cheerio": "1.0.0",
 		"escape-unicode": "^0.3.0",
 		"escope": "^4.0.0",
@@ -109,9 +109,9 @@
 	"devDependencies": {
 		"@istanbuljs/esm-loader-hook": "^0.3.0",
 		"@jridgewell/trace-mapping": "^0.3.31",
-		"@ui5/project": "^5.0.0-alpha.3",
+		"@ui5/project": "^5.0.0-alpha.4",
 		"ava": "^6.4.1",
-		"cross-env": "^7.0.3",
+		"cross-env": "^10.1.0",
 		"eslint": "^9.36.0",
 		"esmock": "^2.7.3",
 		"line-column": "^1.0.2",