build: show deletion target in docs (#9648)

* Surfaces the @deletion-target JSDoc information into the Dgeni HTML output. Currently it will add a title to the deprecation marker.

Closes #9641

Author: devversion

tools/dgeni/common/decorators.ts

@@ -6,7 +6,7 @@
 import {ClassExportDoc} from 'dgeni-packages/typescript/api-doc-types/ClassExportDoc';
 import {PropertyMemberDoc} from 'dgeni-packages/typescript/api-doc-types/PropertyMemberDoc';
 import {MemberDoc} from 'dgeni-packages/typescript/api-doc-types/MemberDoc';
-import {CategorizedClassDoc} from './dgeni-definitions';
+import {CategorizedClassDoc, DeprecationDoc, HasDecoratorsDoc} from './dgeni-definitions';
 
 const SELECTOR_BLACKLIST = new Set([
   '[portal]',
@@ -76,16 +76,34 @@ export function hasClassDecorator(doc: ClassExportDoc, decoratorName: string) {
   return doc.docType == 'class' && hasDecorator(doc, decoratorName);
 }
 
-export function hasDecorator(doc: {decorators?: {name: string}[]}, decoratorName: string) {
+export function hasDecorator(doc: HasDecoratorsDoc, decoratorName: string) {
   return !!doc.decorators &&
     doc.decorators.length > 0 &&
     doc.decorators.some(d => d.name == decoratorName);
 }
 
+export function getDeletionTarget(doc: any): string | null {
+  if (!doc.tags) {
+    return null;
+  }
+
+  const deletionTarget = doc.tags.tags.find((t: any) => t.tagName === 'deletion-target');
+
+  return deletionTarget ? deletionTarget.description : null;
+}
+
 /**
  * Decorates public exposed docs. Creates a property on the doc that indicates whether
  * the item is deprecated or not.
  */
-export function decorateDeprecatedDoc(doc: {isDeprecated: boolean}) {
+export function decorateDeprecatedDoc(doc: DeprecationDoc) {
   doc.isDeprecated = isDeprecatedDoc(doc);
+  doc.deletionTarget = getDeletionTarget(doc);
+
+  if (doc.isDeprecated && !doc.deletionTarget) {
+    console.warn('Warning: There is a deprecated item without a @deletion-target tag.', doc.id);
+  } else if  (doc.deletionTarget && !doc.isDeprecated) {
+    console.warn('Warning: There is an item with a @deletion-target which is not deprecated.',
+      doc.id);
+  }
 }

tools/dgeni/common/dgeni-definitions.ts

@@ -1,13 +1,25 @@
+import {ApiDoc} from 'dgeni-packages/typescript/api-doc-types/ApiDoc';
 import {ClassExportDoc} from 'dgeni-packages/typescript/api-doc-types/ClassExportDoc';
 import {ClassLikeExportDoc} from 'dgeni-packages/typescript/api-doc-types/ClassLikeExportDoc';
 import {PropertyMemberDoc} from 'dgeni-packages/typescript/api-doc-types/PropertyMemberDoc';
+import {ParsedDecorator} from 'dgeni-packages/typescript/services/TsParser/getDecorators';
 import {NormalizedMethodMemberDoc} from './normalize-method-parameters';
 
+/** Interface that describes categorized docs that can be deprecated. */
+export interface DeprecationDoc extends ApiDoc {
+  isDeprecated: boolean;
+  deletionTarget: string | null;
+}
+
+/** Interface that describes Dgeni documents that have decorators. */
+export interface HasDecoratorsDoc {
+  decorators?: ParsedDecorator[] | undefined;
+}
+
 /** Extended Dgeni class-like document that includes separated class members. */
-export interface CategorizedClassLikeDoc extends ClassLikeExportDoc {
+export interface CategorizedClassLikeDoc extends ClassLikeExportDoc, DeprecationDoc {
   methods: CategorizedMethodMemberDoc[];
   properties: CategorizedPropertyMemberDoc[];
-  isDeprecated: boolean;
 }
 
 /** Extended Dgeni class document that includes extracted Angular metadata. */
@@ -22,17 +34,15 @@ export interface CategorizedClassDoc extends ClassExportDoc, CategorizedClassLik
 }
 
 /** Extended Dgeni property-member document that includes extracted Angular metadata. */
-export interface CategorizedPropertyMemberDoc extends PropertyMemberDoc {
+export interface CategorizedPropertyMemberDoc extends PropertyMemberDoc, DeprecationDoc {
   description: string;
-  isDeprecated: boolean;
   isDirectiveInput: boolean;
   isDirectiveOutput: boolean;
   directiveInputAlias: string;
   directiveOutputAlias: string;
 }
 
 /** Extended Dgeni method-member document that simplifies logic for the Dgeni template. */
-export interface CategorizedMethodMemberDoc extends NormalizedMethodMemberDoc {
+export interface CategorizedMethodMemberDoc extends NormalizedMethodMemberDoc, DeprecationDoc {
   showReturns: boolean;
-  isDeprecated: boolean;
 }

tools/dgeni/templates/class.template.html

@@ -1,3 +1,5 @@
+{% import "macros.html" as macros %}
+
 <h4 id="{$ class.name $}" class="docs-header-link docs-api-h4 docs-api-class-name">
   <span header-link="{$ class.name $}"></span>
   <code>{$ class.name $}</code>
@@ -28,7 +30,9 @@ <h4 id="{$ class.name $}" class="docs-header-link docs-api-h4 docs-api-class-nam
 {%- endif -%}
 
 {%- if class.isDeprecated -%}
-<div class="docs-api-class-deprecated-marker">Deprecated</div>
+<div class="docs-api-class-deprecated-marker" {$ macros.deprecationTitle(class) $}>
+  Deprecated
+</div>
 {%- endif -%}
 
 {$ propertyList(class.properties) $}

tools/dgeni/templates/interface.template.html

@@ -1,3 +1,5 @@
+{% import "macros.html" as macros %}
+
 <h4 id="{$ interface.name $}" class="docs-header-link docs-api-h4 docs-api-interface-name">
   <span header-link="{$ interface.name $}"></span>
   <code>{$ interface.name $}</code>
@@ -8,7 +10,9 @@ <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">Deprecated</div>
+<div class="docs-api-interface-deprecated-marker" {$ macros.deprecationTitle(interface) $}>
+  Deprecated
+</div>
 {%- endif -%}
 
 {$ propertyList(interface.properties) $}

tools/dgeni/templates/macros.html

@@ -0,0 +1,5 @@
+{% macro deprecationTitle(doc) %}
+  {%- if doc.deletionTarget -%}
+    title="Will be deleted in v{$ doc.deletionTarget $}"
+  {%- endif -%}
+{% endmacro %}

tools/dgeni/templates/method.template.html

@@ -1,9 +1,13 @@
+{% import "macros.html" as macros %}
+
 <table class="docs-api-method-table">
   <thead>
     <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">Deprecated</div>
+          <div class="docs-api-deprecated-marker" {$ macros.deprecationTitle(method) $}>
+            Deprecated
+          </div>
         {%- endif -%}   
         {$ method.name $}
       </th>

tools/dgeni/templates/property.template.html

@@ -1,3 +1,5 @@
+{% import "macros.html" as macros %}
+
 <tr class="docs-api-properties-row">
   <td class="docs-api-properties-name-cell">
     {%- if property.isDirectiveInput -%}
@@ -19,7 +21,9 @@
       </div>
     {%- endif -%}
     {%- if property.isDeprecated -%}
-      <div class="docs-api-deprecated-marker">Deprecated</div>
+      <div class="docs-api-deprecated-marker" {$ macros.deprecationTitle(property) $}>
+        Deprecated
+      </div>
     {%- endif -%}   
 
     <p class="docs-api-property-name">