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.

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,25 @@ 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 with CSS classes that will be 
+   * added to the template.
+   **/
+  function decoratePublicDoc(doc) {
+    // Specific classes that will can added to the Dgeni doc template.
+    doc.docClasses = [
+      isDeprecatedDoc(doc) ? 'docs-api-deprecated' : ''
+    ].join(' ');
+  }
 };
 
 /** Function that walks through all inherited docs and collects public methods. */
@@ -146,6 +162,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

@@ -1,13 +1,15 @@
-<h4 class="docs-api-h4 docs-api-class-name">
-  <code>{$ class.name $}</code>
-</h4>
-<p class="docs-api-class-description">{$ class.description $}</p>
+<div class="{$ class.docClasses $}">
+  <h4 class="docs-api-h4 docs-api-class-name">
+    <code>{$ class.name $}</code>
+  </h4>
+  <p class="docs-api-class-description">{$ class.description $}</p>
 
-{%- if class.directiveExportAs -%}
-<span class="docs-api-h4 docs-api-class-export-label">Exported as:</span>
-<span class="docs-api-class-export-name">{$ class.directiveExportAs $}</span>
-{%- endif -%}
+  {%- if class.directiveExportAs -%}
+  <span class="docs-api-h4 docs-api-class-export-label">Exported as:</span>
+  <span class="docs-api-class-export-name">{$ class.directiveExportAs $}</span>
+  {%- endif -%}
 
-{$ propertyList(class.properties) $}
+  {$ propertyList(class.properties) $}
 
-{$ methodList(class.methods) $}
+  {$ methodList(class.methods) $}
+</div>

tools/dgeni/templates/method.template.html

@@ -1,4 +1,4 @@
-<table class="docs-api-method-table">
+<table class="docs-api-method-table {$ method.docClasses $}">
   <thead>
     <tr class="docs-api-method-name-row">
       <th colspan="2" class="docs-api-method-name-cell">{$ method.name $}</th>

tools/dgeni/templates/property.template.html

@@ -1,4 +1,4 @@
-<tr class="docs-api-properties-row">
+<tr class="docs-api-properties-row {$ property.docClasses $}">
   <td class="docs-api-properties-name-cell">
     {%- if property.isDirectiveInput -%}
       <div class="docs-api-input-marker">