feat(dgeni): add deprecated field to API doc

Author: griest024

libs/docs-utils/src/doc/api.type.ts

@@ -7,4 +7,5 @@ import { DaffDocExample } from '../example/public_api';
 export interface DaffApiDoc extends DaffDoc {
   docType: string;
   examples: Array<DaffDocExample>;
+  deprecated: boolean;
 }

tools/dgeni/src/processors/markdown.ts

@@ -81,9 +81,6 @@ export class MarkdownCodeProcessor implements FilterableProcessor {
           doc.longDescription = this.parse(doc.longDescription).replaceAll(/(^<p>)|(<\/p>(\n)*$)/gm, '');
         }
         doc.slug = slugify(doc.name || doc.title);
-        if (doc.sourceApiBlock) {
-          doc.sourceApiBlock = this.parse(`\`\`\`ts\n${doc.sourceApiBlock}\n\`\`\``);
-        }
       };
       return doc;
     });

tools/dgeni/src/transforms/daffodil-api-package/index.ts

@@ -21,6 +21,10 @@ import {
   ADD_SUBPACKAGE_EXPORTS_PROCESSOR_NAME,
   ADD_SUBPACKAGE_EXPORTS_PROCESSOR_PROVIDER,
 } from './processors/add-subpackage-exports';
+import {
+  DEPRECATED_PROCESSOR_PROVIDER,
+  DeprecatedProcessor,
+} from './processors/deprecated';
 import { RemoveDuplicatesProcessor } from './processors/remove-duplicates';
 import { DAFF_DGENI_EXCLUDED_PACKAGES_REGEX } from '../../constants/excluded-packages';
 import { AddKindProcessor } from '../../processors/add-kind';
@@ -70,6 +74,7 @@ export const apiDocsBase = new Package('api-base', [
   .processor(...COLLECT_LINKABLE_SYMBOLS_PROCESSOR_PROVIDER)
   .processor(...EXAMPLES_PROCESSOR_PROVIDER)
   .processor(...ADD_SOURCE_PROVIDER)
+  .processor(...DEPRECATED_PROCESSOR_PROVIDER)
   .factory('API_DOC_TYPES_TO_RENDER', (EXPORT_DOC_TYPES) => EXPORT_DOC_TYPES.concat(['component', 'directive', 'pipe']))
   .config((readFilesProcessor, readTypeScriptModules, tsParser) => {
 
@@ -91,7 +96,9 @@ export const apiDocsBase = new Package('api-base', [
     breadcrumb: BreadcrumbProcessor,
     examples: ExamplesProcessor,
     addSource: AddSourceProcessor,
+    deprecated: DeprecatedProcessor,
   ) => {
+    deprecated.docTypes.push(...EXPORT_DOC_TYPES);
     markdown.docTypes.push(...EXPORT_DOC_TYPES);
     examples.docTypes.push(...EXPORT_DOC_TYPES);
     markdown.docTypes.push(...EXPORT_DOC_TYPES);
@@ -135,7 +142,7 @@ export const apiDocsBase = new Package('api-base', [
   })
   .config((convertToJson: ConvertToJsonProcessor, API_DOC_TYPES_TO_RENDER) => {
     convertToJson.docTypes = convertToJson.docTypes.concat(API_DOC_TYPES_TO_RENDER);
-    convertToJson.extraFields.push('examples');
+    convertToJson.extraFields.push('examples', 'deprecated');
   })
   .config((templateFinder) => {
     // Where to find the templates for the API doc rendering

tools/dgeni/src/transforms/daffodil-api-package/processors/add-source.ts

@@ -8,8 +8,8 @@ import type { MemberDoc } from 'dgeni-packages/typescript/api-doc-types/MemberDo
 import { MethodMemberDoc } from 'dgeni-packages/typescript/api-doc-types/MethodMemberDoc';
 import { PropertyMemberDoc } from 'dgeni-packages/typescript/api-doc-types/PropertyMemberDoc';
 import type { TypeAliasExportDoc } from 'dgeni-packages/typescript/api-doc-types/TypeAliasExportDoc';
+import { MarkdownCodeProcessor } from 'tools/dgeni/src/processors/markdown';
 
-import { MARKDOWN_CODE_PROCESSOR_NAME } from '../../../processors/markdown';
 import { FilterableProcessor } from '../../../utils/filterable-processor.type';
 import { htmlDecodeBrackets } from '../../../utils/html-brackets';
 
@@ -49,7 +49,9 @@ const enumBlock = (doc: EnumExportDoc): string => {
 
 const interfaceBlock = (doc: InterfaceExportDoc): string => {
   const members = doc.members.reduce((acc, member) =>
-    `${acc}${tab()}${getMemberModifiers(member)}${member.name}: ${member.type}\n`
+    (<any>member).deprecated//
+      ? `${acc}${tab()}~a~${getMemberModifiers(member)}${member.name}: ${member.type}~z~\n`
+      : `${acc}${tab()}${getMemberModifiers(member)}${member.name}: ${member.type}\n`
   , '\n');
 
   return `interface ${doc.name}${doc.typeParams} {${members}}`;
@@ -105,7 +107,9 @@ const classMember = (doc: ClassMember): string => {
       return property;
     }
 
-    return `${decorators}${getMemberModifiers(doc)}${doc.name}${type}`;
+    return (<any>doc).deprecated
+      ? `~a~${decorators}${getMemberModifiers(doc)}${doc.name}${type}~z~`
+      : `${decorators}${getMemberModifiers(doc)}${doc.name}${type}`;
   }
 
   return '';
@@ -148,7 +152,7 @@ export const ADD_SOURCE_NAME = 'addSource';
 export class AddSourceProcessor implements FilterableProcessor {
   readonly name = ADD_SOURCE_NAME;
   readonly $runAfter = ['paths-absolutified'];
-  readonly $runBefore = ['rendering-docs', MARKDOWN_CODE_PROCESSOR_NAME];
+  readonly $runBefore = ['rendering-docs'];
 
   docTypes = [];
 
@@ -177,10 +181,16 @@ export class AddSourceProcessor implements FilterableProcessor {
     }
   }
 
+  constructor(
+    private markdown: MarkdownCodeProcessor,
+  ) {}
+
   $process(docs: Array<Document>): Array<Document> {
     return docs.map(doc => {
       if (this.docTypes.includes(doc.docType)) {
-        doc.sourceApiBlock = htmlDecodeBrackets(this.getSourceBlock(doc));
+        doc.sourceApiBlock = this.markdown.parse(`\`\`\`ts\n${htmlDecodeBrackets(this.getSourceBlock(doc))}\n\`\`\``)
+          .replaceAll('~a~', '<strike>')
+          .replaceAll('~z~', '</strike>');
       }
       return doc;
     });
@@ -189,5 +199,5 @@ export class AddSourceProcessor implements FilterableProcessor {
 
 export const ADD_SOURCE_PROVIDER = <const>[
   ADD_SOURCE_NAME,
-  () => new AddSourceProcessor(),
+  (markdown: MarkdownCodeProcessor) => new AddSourceProcessor(markdown),
 ];

tools/dgeni/src/transforms/daffodil-api-package/processors/deprecated.ts

@@ -0,0 +1,31 @@
+import { Document } from 'dgeni';
+
+
+import { FilterableProcessor } from '../../../utils/filterable-processor.type';
+
+export const DEPRECATED_PROCESSOR_NAME = 'deprecated';
+
+/**
+ * Adds subpackage entry point docs to the containing package doc.
+ */
+export class DeprecatedProcessor implements FilterableProcessor {
+  readonly name = DEPRECATED_PROCESSOR_NAME;
+  readonly $runAfter = ['docs-processed'];
+  readonly $runBefore = ['rendering-docs'];
+
+  docTypes = [];
+
+  $process(docs: Array<Document>): Array<Document> {
+    return docs.map((doc) => {
+      if (this.docTypes.includes(doc.docType)) {
+        doc.deprecated = !!doc.tags.getTag('deprecated');
+      }
+      return doc;
+    });
+  }
+}
+
+export const DEPRECATED_PROCESSOR_PROVIDER = <const>[
+  DEPRECATED_PROCESSOR_NAME,
+  () => new DeprecatedProcessor(),
+];