From 9ca610a4575c04a1f28bcee7668b89d6a8863cd8 Mon Sep 17 00:00:00 2001
From: naaajii <vcmpbhai@gmail.com>
Date: Mon, 14 Oct 2024 04:16:28 +0500
Subject: [PATCH] build: update dgeni templates to include `deprecated` tag
 description

changes how deprecated fields are generated for docs content, before this commit deprecated related
text was shown via `title` attribute on hover and the `deprecated` tag description was never shown
unless user check it manually via code. this commit exports `deprecated` tag description to
reflect it directly in docs using `material/tooltip` on doc site
---
 tools/dgeni/common/decorators.ts        | 8 +++++++-
 tools/dgeni/common/dgeni-definitions.ts | 1 +
 tools/dgeni/templates/macros.html       | 6 ++++--
 3 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/tools/dgeni/common/decorators.ts b/tools/dgeni/common/decorators.ts
index 86a10b1acac6..5a212003eeea 100644
--- a/tools/dgeni/common/decorators.ts
+++ b/tools/dgeni/common/decorators.ts
@@ -85,13 +85,19 @@ export function getBreakingChange(doc: ApiDoc): string | null {
   return breakingChange ? breakingChange.description : null;
 }
 
+export function getDeprecationMessage(doc: ApiDoc): string | null {
+  const deprecatedMessage = findJsDocTag(doc, 'deprecated');
+  return deprecatedMessage ? deprecatedMessage.description : null;
+}
+
 /**
  * Decorates public exposed docs. Creates a property on the doc that indicates whether
- * the item is deprecated or not.
+ * the item is deprecated or not and set deprecation message.
  */
 export function decorateDeprecatedDoc(doc: ApiDoc & DeprecationInfo) {
   doc.isDeprecated = isDeprecatedDoc(doc);
   doc.breakingChange = getBreakingChange(doc);
+  doc.deprecatedMessage = getDeprecationMessage(doc);
 
   if (doc.isDeprecated && !doc.breakingChange) {
     console.warn('Warning: There is a deprecated item without a @breaking-change tag.', doc.id);
diff --git a/tools/dgeni/common/dgeni-definitions.ts b/tools/dgeni/common/dgeni-definitions.ts
index 9be3177b044f..5b7865b61de4 100644
--- a/tools/dgeni/common/dgeni-definitions.ts
+++ b/tools/dgeni/common/dgeni-definitions.ts
@@ -12,6 +12,7 @@ import {NormalizedFunctionParameters} from './normalize-function-parameters';
 export interface DeprecationInfo {
   isDeprecated: boolean;
   breakingChange: string | null;
+  deprecatedMessage: string | null;
 }
 
 /** Interface that describes Dgeni documents that have decorators. */
diff --git a/tools/dgeni/templates/macros.html b/tools/dgeni/templates/macros.html
index 55242db57a7d..909e4bb8a56a 100644
--- a/tools/dgeni/templates/macros.html
+++ b/tools/dgeni/templates/macros.html
@@ -1,5 +1,7 @@
 {% macro deprecationTitle(doc) %}
-  {%- if doc.breakingChange -%}
-    title="Will be removed in v{$ doc.breakingChange $} or later"
+  {%- if doc.breakingChange and doc.deprecatedMessage -%}
+    deprecated-message="{$ doc.deprecatedMessage $} Will be removed in v{$ doc.breakingChange $} or later."
+  {% else %}
+    deprecated-message="{$ doc.deprecatedMessage $}"
   {%- endif -%}
 {% endmacro %}