Update api-documenter's YAML generator to support @sealed/@virtual/@OverRide

Author: pgonzal

apps/api-documenter/src/yaml/YamlDocumenter.ts

@@ -16,7 +16,8 @@ import {
   IApiEnumMember,
   IApiClass,
   IApiInterface,
-  Markup
+  Markup,
+  ApiItem
 } from '@microsoft/api-extractor';
 
 import { DocItemSet, DocItem, DocItemKind, IDocItemSetResolveResult } from '../utils/DocItemSet';
@@ -300,14 +301,28 @@ export class YamlDocumenter {
     if (apiStructure.implements) {
       yamlItem.implements = [ apiStructure.implements ];
     }
+
+    if (apiStructure.isSealed) {
+      let sealedMessage: string;
+      if (docItem.kind === DocItemKind.Class) {
+        sealedMessage = 'This class is marked as `@sealed`. Subclasses should not extend it.';
+      } else {
+        sealedMessage = 'This interface is marked as `@sealed`. Other interfaces should not extend it.';
+      }
+      if (!yamlItem.remarks) {
+        yamlItem.remarks = sealedMessage;
+      } else {
+        yamlItem.remarks += sealedMessage + '\n\n' + yamlItem.remarks;
+      }
+    }
   }
 
   private _populateYamlMethod(yamlItem: Partial<IYamlItem>, docItem: DocItem): void {
     const apiMethod: IApiMethod | IApiConstructor = docItem.apiItem as IApiMethod;
     yamlItem.name = Utilities.getConciseSignature(docItem.name, apiMethod);
 
     const syntax: IYamlSyntax = {
-      content: apiMethod.signature
+      content: this._formatCommentedAnnotations(apiMethod.signature, apiMethod)
     };
     yamlItem.syntax = syntax;
 
@@ -343,8 +358,9 @@ export class YamlDocumenter {
     const apiProperty: IApiProperty = docItem.apiItem as IApiProperty;
 
     const syntax: IYamlSyntax = {
-      content: apiProperty.signature
+      content: this._formatCommentedAnnotations(apiProperty.signature, apiProperty)
     };
+
     yamlItem.syntax = syntax;
 
     if (apiProperty.type) {
@@ -397,6 +413,27 @@ export class YamlDocumenter {
     }
   }
 
+  // Prepends a string such as "/** @sealed @override */" to an item signature where appropriate.
+  private _formatCommentedAnnotations(signature: string, apiItem: ApiItem): string {
+    const apiItemTags: { isSealed?: boolean, isVirtual?: boolean, isOverride?: boolean }
+      = apiItem as any; // tslint:disable-line:no-any
+
+    const annotations: string[] = [];
+    if (apiItemTags.isSealed) {
+      annotations.push('@sealed');
+    }
+    if (apiItemTags.isVirtual) {
+      annotations.push('@virtual');
+    }
+    if (apiItemTags.isOverride) {
+      annotations.push('@override');
+    }
+    if (annotations.length === 0) {
+      return signature;
+    }
+    return '/** ' + annotations.join(' ') + ' */\n' + signature;
+  }
+
   /**
    * Calculate the docfx "uid" for the DocItem
    * Example:  node-core-library.JsonFile.load