[INTERNAL] JSDoc: push the deprecation of namespaces down to the contained APIs

codeworrior · codeworrior · commit b16b6bcaab6d · 2025-12-08T20:28:02.000+01:00
Change-Id: I67f019d4f966b1dcb15c869e437e6feffbb0c574
diff --git a/lib/jsdoc/ui5/template/publish.js b/lib/jsdoc/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 ----------------------------------------------------------------------------
 
 /*
