build: dgeni add deprecated marker (#4028)

* build: dgeni add deprecated marker

* Adds a class to property rows in the template that can be used to distinguish between deprecated and stable APIs.

Fixes #3981.

* Address feedback

Author: devversion

tools/dgeni/processors/categorizer.js

@@ -28,6 +28,8 @@ module.exports = function categorizer() {
     classDoc.methods.forEach(doc => decorateMethodDoc(doc));
     classDoc.properties.forEach(doc => decoratePropertyDoc(doc));
 
+    decoratePublicDoc(classDoc);
+    
     // Categorize the current visited classDoc into its Angular type.
     if (isDirective(classDoc)) {
       classDoc.isDirective = true;
@@ -45,6 +47,7 @@ module.exports = function categorizer() {
    */
   function decorateMethodDoc(methodDoc) {
     normalizeMethodParameters(methodDoc);
+    decoratePublicDoc(methodDoc);
 
     // Mark methods with a `void` return type so we can omit show the return type in the docs.
     methodDoc.showReturns = methodDoc.returnType && methodDoc.returnType != 'void';
@@ -55,12 +58,22 @@ module.exports = function categorizer() {
    * outputs will be marked. Aliases for the inputs or outputs will be stored as well.
    */
   function decoratePropertyDoc(propertyDoc) {
+    decoratePublicDoc(propertyDoc);
+
     propertyDoc.isDirectiveInput = isDirectiveInput(propertyDoc);
     propertyDoc.directiveInputAlias = getDirectiveInputAlias(propertyDoc);
 
     propertyDoc.isDirectiveOutput = isDirectiveOutput(propertyDoc);
     propertyDoc.directiveOutputAlias = getDirectiveOutputAlias(propertyDoc);
   }
+
+  /**
+   * Decorates public exposed docs. Creates a property on the doc that indicates whether
+   * the item is deprecated or not.
+   **/
+  function decoratePublicDoc(doc) {
+    doc.isDeprecated = isDeprecatedDoc(doc);
+  }
 };
 
 /** Function that walks through all inherited docs and collects public methods. */
@@ -146,6 +159,10 @@ function isDirectiveInput(doc) {
   return hasMemberDecorator(doc, 'Input');
 }
 
+function isDeprecatedDoc(doc) {
+  return (doc.tags && doc.tags.tags || []).some(tag => tag.tagName === 'deprecated');
+}
+
 function getDirectiveInputAlias(doc) {
   return isDirectiveInput(doc) ? doc.decorators.find(d => d.name == 'Input').arguments[0] : '';
 }

tools/dgeni/templates/class.template.html

@@ -8,6 +8,10 @@ <h4 class="docs-api-h4 docs-api-class-name">
 <span class="docs-api-class-export-name">{$ class.directiveExportAs $}</span>
 {%- endif -%}
 
+{%- if class.isDeprecated -%}
+<div class="docs-api-class-deprecated-marker">Deprecated</div>
+{%- endif -%}   
+
 {$ propertyList(class.properties) $}
 
 {$ methodList(class.methods) $}

tools/dgeni/templates/method.template.html

@@ -1,7 +1,12 @@
 <table class="docs-api-method-table">
   <thead>
     <tr class="docs-api-method-name-row">
-      <th colspan="2" class="docs-api-method-name-cell">{$ method.name $}</th>
+      <th colspan="2" class="docs-api-method-name-cell">
+        {%- if method.isDeprecated -%}
+          <div class="docs-api-deprecated-marker">Deprecated</div>
+        {%- endif -%}   
+        {$ method.name $}
+      </th>
     </tr>
   </thead>
   <tr class="docs-api-method-description-row">

tools/dgeni/templates/property.template.html

@@ -18,6 +18,9 @@
         {%- endif -%}
       </div>
     {%- endif -%}
+    {%- if property.isDeprecated -%}
+      <div class="docs-api-deprecated-marker">Deprecated</div>
+    {%- endif -%}   
 
     <p class="docs-api-property-name">
       {$ property.name $}