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

Author: naaajii

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);

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. */

tools/dgeni/templates/class.template.html

@@ -1,8 +1,13 @@
 {% import "macros.html" as macros %}
 
 <h4 id="{$ class.name $}" class="docs-header-link docs-api-h4 docs-api-class-name">
+  {%- if class.isDeprecated -%}
+  <span header-link="{$ class.name $}"></span>
+  <code class="docs-api-class-deprecated-marker" {$ macros.deprecationTitle(class, class.name) $}></code>
+  {% else %}
   <span header-link="{$ class.name $}"></span>
   <code>{$ class.name $}</code>
+  {%- endif -%}
   {% if class.extendedDoc %}
   <span class="docs-api-class-extends-clauses">
     <span class="docs-api-class-extends-label">extends</span>
@@ -31,12 +36,6 @@ <h4 id="{$ class.name $}" class="docs-header-link docs-api-h4 docs-api-class-nam
 <span class="docs-api-class-export-name">{$ class.directiveExportAs $}</span>
 {%- endif -%}
 
-{%- if class.isDeprecated -%}
-<div class="docs-api-class-deprecated-marker" {$ macros.deprecationTitle(class) $}>
-  Deprecated
-</div>
-{%- endif -%}
-
 {$ propertyList(class.properties) $}
 
 {$ methodList(class.methods) $}

tools/dgeni/templates/constant.template.html

@@ -6,9 +6,7 @@ <h4 id="{$ constant.name $}" class="docs-header-link docs-api-h4 docs-api-consta
 </h4>
 
 {%- if constant.isDeprecated -%}
-<div class="docs-api-constant-deprecated-marker" {$ macros.deprecationTitle(constant) $}>
-  Deprecated
-</div>
+<div class="docs-api-constant-deprecated-marker" {$ macros.deprecationTitle(constant, "Deprecated") $}></div>
 {%- endif -%}
 
 {%- if constant.description -%}

tools/dgeni/templates/interface.template.html

@@ -10,9 +10,7 @@ <h4 id="{$ interface.name $}" class="docs-header-link docs-api-h4 docs-api-inter
 {%- endif -%}
 
 {%- if interface.isDeprecated -%}
-<div class="docs-api-interface-deprecated-marker" {$ macros.deprecationTitle(interface) $}>
-  Deprecated
-</div>
+<div class="docs-api-interface-deprecated-marker" {$ macros.deprecationTitle(interface, "Deprecated") $}></div>
 {%- endif -%}
 
 {$ propertyList(interface.properties) $}

tools/dgeni/templates/macros.html

@@ -1,5 +1,9 @@
-{% macro deprecationTitle(doc) %}
-  {%- if doc.breakingChange -%}
-    title="Will be removed in v{$ doc.breakingChange $} or later"
+{% macro deprecationTitle(doc, innerText) %}
+  {%- if doc.breakingChange and doc.deprecatedMessage -%}
+    depreciation-title="{$ doc.deprecatedMessage $} Will be removed in v{$ doc.breakingChange $} or later."
+    inner-text="{$ innerText $}"
+  {% else %}
+    depreciation-title="{$ doc.deprecatedMessage $}"
+    inner-text="{$ innerText $}"
   {%- endif -%}
 {% endmacro %}

tools/dgeni/templates/method.template.html

@@ -5,9 +5,7 @@
     <tr class="docs-api-method-name-row">
       <th colspan="2" class="docs-api-method-name-cell">
         {%- if method.isDeprecated -%}
-          <div class="docs-api-deprecated-marker" {$ macros.deprecationTitle(method) $}>
-            Deprecated
-          </div>
+          <div class="docs-api-deprecated-marker" {$ macros.deprecationTitle(method, "Deprecated") $}></div>
         {%- endif -%}
         {%- if method.isStatic -%}
         <div class="docs-api-modifier-method-marker">

tools/dgeni/templates/property.template.html

@@ -21,9 +21,7 @@
       </div>
     {%- endif -%}
     {%- if property.isDeprecated -%}
-      <div class="docs-api-deprecated-marker" {$ macros.deprecationTitle(property) $}>
-        Deprecated
-      </div>
+      <div class="docs-api-deprecated-marker" {$ macros.deprecationTitle(property, "Deprecated") $}></div>
     {%- endif -%}
 
     <p class="docs-api-property-name">

tools/dgeni/templates/type-alias.template.html

@@ -6,9 +6,7 @@ <h4 id="{$ alias.name $}" class="docs-header-link docs-api-h4 docs-api-type-alia
 </h4>
 
 {%- if alias.isDeprecated -%}
-<div class="docs-api-type-alias-deprecated-marker" {$ macros.deprecationTitle(alias) $}>
-  Deprecated
-</div>
+<div class="docs-api-type-alias-deprecated-marker" {$ macros.deprecationTitle(alias, "Deprecated") $}></div>
 {%- endif -%}
 
 {%- if alias.description -%}