[api-extractor] Add support for @example in AEDoc

apps/api-extractor/src/ResolvedApiItem.ts

@@ -16,6 +16,7 @@ export class ResolvedApiItem {
   public kind: AstItemKind;
   public summary: MarkupElement[];
   public remarks: MarkupElement[];
+  public examples: MarkupElement[][];
   public deprecatedMessage: MarkupBasicElement[] | undefined;
   public releaseTag: ReleaseTag;
   public isBeta: boolean;
@@ -35,6 +36,7 @@ export class ResolvedApiItem {
       astItem.kind,
       astItem.documentation.summary,
       astItem.documentation.remarks,
+      astItem.documentation.examples,
       astItem.documentation.deprecatedMessage,
       astItem.documentation.releaseTag === ReleaseTag.Beta,
       astItem.documentation.parameters,
@@ -68,6 +70,7 @@ export class ResolvedApiItem {
       ApiJsonConverter.convertJsonToKind(docItem.kind),
       docItem.summary,
       docItem.remarks,
+      docItem.examples,
       docItem.deprecatedMessage,
       docItem.isBeta,
       parameters,
@@ -81,6 +84,7 @@ export class ResolvedApiItem {
     kind: AstItemKind,
     summary: MarkupElement[],
     remarks: MarkupElement[],
+    examples: MarkupElement[][],
     deprecatedMessage: MarkupBasicElement[] | undefined,
     isBeta: boolean,
     params: { [name: string]: IAedocParameter } | undefined,
@@ -90,6 +94,7 @@ export class ResolvedApiItem {
     this.kind = kind;
     this.summary = summary;
     this.remarks = remarks;
+    this.examples = examples;
     this.deprecatedMessage = deprecatedMessage;
     this.isBeta = isBeta;
     this.params = params;

apps/api-extractor/src/aedoc/ApiDocumentation.ts

@@ -49,6 +49,7 @@ export class ApiDocumentation {
     '@beta',
     '@betadocumentation',
     '@eventproperty',
+    '@example',
     '@internal',
     '@internalremarks',
     '@override',
@@ -83,6 +84,7 @@ export class ApiDocumentation {
   public summary: MarkupElement[];
   public deprecatedMessage: MarkupBasicElement[];
   public remarks: MarkupElement[];
+  public examples: MarkupElement[][];
   public returnsMessage: MarkupBasicElement[];
   public parameters: { [name: string]: IAedocParameter; };
 
@@ -233,6 +235,7 @@ export class ApiDocumentation {
     this.returnsMessage = [];
     this.deprecatedMessage = [];
     this.remarks = [];
+    this.examples = [];
     this.incompleteLinks = [];
     this.incompleteInheritdocs = [];
     this.releaseTag = ReleaseTag.None;
@@ -263,6 +266,11 @@ export class ApiDocumentation {
             this._checkInheritDocStatus(token.tag);
             this.remarks = DocElementParser.parseAndNormalize(this, tokenizer);
             break;
+          case '@example':
+            tokenizer.getToken();
+            this._checkInheritDocStatus(token.tag);
+            this.examples.push(DocElementParser.parseAndNormalize(this, tokenizer));
+            break;
           case '@returns':
             tokenizer.getToken();
             this._checkInheritDocStatus(token.tag);

apps/api-extractor/src/aedoc/DocElementParser.ts

@@ -262,6 +262,7 @@ export class DocElementParser {
     // inheritdoc found, copy over IApiBaseDefinition properties
     documentation.summary =  resolvedAstItem.summary;
     documentation.remarks = resolvedAstItem.remarks;
+    documentation.examples = resolvedAstItem.examples;
 
     // Copy over detailed properties if neccessary
     // Add additional cases if needed

apps/api-extractor/src/api/ApiItem.ts

@@ -122,6 +122,7 @@ export interface IApiBaseDefinition {
   isBeta: boolean;
   summary: MarkupBasicElement[];
   remarks: MarkupStructuredElement[];
+  examples: MarkupStructuredElement[][],
   deprecatedMessage?: MarkupBasicElement[];
 }
 
@@ -448,6 +449,7 @@ export interface IApiPackage {
   isBeta: boolean;
   summary: MarkupBasicElement[];
   remarks: MarkupStructuredElement[];
+  examples: MarkupStructuredElement[][],
   deprecatedMessage?: MarkupBasicElement[];
 }
 

apps/api-extractor/src/api/api-json.schema.json

@@ -438,6 +438,14 @@
           "type": "array",
           "items": { "$ref": "#/definitions/markupStructuredElement" }
         },
+        "examples": {
+          "description": "Example regarding usage of the item",
+          "type": "array",
+          "items": { 
+            "type": "array",
+            "items": { "$ref": "#/definitions/markupStructuredElement" }
+          }
+        },
         "deprecatedMessage": {
           "description": "If present, indicates that the item is deprecated and describes the recommended alternative",
           "type": "array",
@@ -513,6 +521,14 @@
           "type": "array",
           "items": { "$ref": "#/definitions/markupStructuredElement" }
         },
+        "examples": {
+          "description": "Example regarding usage of the item",
+          "type": "array",
+          "items": { 
+            "type": "array",
+            "items": { "$ref": "#/definitions/markupStructuredElement" }
+          }
+        },
         "deprecatedMessage": {
           "description": "If present, indicates that the item is deprecated and describes the recommended alternative",
           "type": "array",
@@ -574,6 +590,14 @@
           "type": "array",
           "items": { "$ref": "#/definitions/markupStructuredElement" }
         },
+        "examples": {
+          "description": "Example regarding usage of the item",
+          "type": "array",
+          "items": { 
+            "type": "array",
+            "items": { "$ref": "#/definitions/markupStructuredElement" }
+          }
+        },
         "deprecatedMessage": {
           "description": "If present, indicates that the item is deprecated and describes the recommended alternative",
           "type": "array",
@@ -678,6 +702,14 @@
           "type": "array",
           "items": { "$ref": "#/definitions/markupStructuredElement" }
         },
+        "examples": {
+          "description": "Example regarding usage of the item",
+          "type": "array",
+          "items": { 
+            "type": "array",
+            "items": { "$ref": "#/definitions/markupStructuredElement" }
+          }
+        },
         "deprecatedMessage": {
           "description": "If present, indicates that the item is deprecated and describes the recommended alternative",
           "type": "array",
@@ -781,6 +813,14 @@
           "type": "array",
           "items": { "$ref": "#/definitions/markupStructuredElement" }
         },
+        "examples": {
+          "description": "Example regarding usage of the item",
+          "type": "array",
+          "items": { 
+            "type": "array",
+            "items": { "$ref": "#/definitions/markupStructuredElement" }
+          }
+        },
         "deprecatedMessage": {
           "description": "If present, indicates that the item is deprecated and describes the recommended alternative",
           "type": "array",
@@ -848,6 +888,14 @@
           "type": "array",
           "items": { "$ref": "#/definitions/markupStructuredElement" }
         },
+        "examples": {
+          "description": "Example regarding usage of the item",
+          "type": "array",
+          "items": { 
+            "type": "array",
+            "items": { "$ref": "#/definitions/markupStructuredElement" }
+          }
+        },
         "deprecatedMessage": {
           "description": "If present, indicates that the item is deprecated and describes the recommended alternative",
           "type": "array",
@@ -898,6 +946,14 @@
           "type": "array",
           "items": { "$ref": "#/definitions/markupStructuredElement" }
         },
+        "examples": {
+          "description": "Example regarding usage of the item",
+          "type": "array",
+          "items": { 
+            "type": "array",
+            "items": { "$ref": "#/definitions/markupStructuredElement" }
+          }
+        },
         "deprecatedMessage": {
           "description": "If present, indicates that the item is deprecated and describes the recommended alternative",
           "type": "array",
@@ -939,6 +995,14 @@
           "type": "array",
           "items": { "$ref": "#/definitions/markupStructuredElement" }
         },
+        "examples": {
+          "description": "Example regarding usage of the item",
+          "type": "array",
+          "items": { 
+            "type": "array",
+            "items": { "$ref": "#/definitions/markupStructuredElement" }
+          }
+        },
         "deprecatedMessage": {
           "description": "If present, indicates that the item is deprecated and describes the recommended alternative",
           "type": "array",
@@ -1004,6 +1068,14 @@
           "type": "array",
           "items": { "$ref": "#/definitions/markupStructuredElement" }
         },
+        "examples": {
+          "description": "Example regarding usage of the item",
+          "type": "array",
+          "items": { 
+            "type": "array",
+            "items": { "$ref": "#/definitions/markupStructuredElement" }
+          }
+        },
         "deprecatedMessage": {
           "description": "If present, indicates that the item is deprecated and describes the recommended alternative",
           "type": "array",
@@ -1064,6 +1136,14 @@
           "type": "array",
           "items": { "$ref": "#/definitions/markupStructuredElement" }
         },
+        "examples": {
+          "description": "Example regarding usage of the item",
+          "type": "array",
+          "items": { 
+            "type": "array",
+            "items": { "$ref": "#/definitions/markupStructuredElement" }
+          }
+        },
         "deprecatedMessage": {
           "description": "If present, indicates that the item is deprecated and describes the recommended alternative",
           "type": "array",
@@ -1103,6 +1183,14 @@
       "type": "array",
       "items": { "$ref": "#/definitions/markupStructuredElement" }
     },
+    "examples": {
+      "description": "Example regarding usage of the item",
+      "type": "array",
+      "items": { 
+        "type": "array",
+        "items": { "$ref": "#/definitions/markupStructuredElement" }
+      }
+    },
     "exports": {
       "description": "The exported definitions for this API package",
       "type": "object",

apps/api-extractor/src/generators/ApiJsonGenerator.ts

@@ -93,6 +93,7 @@ export class ApiJsonGenerator extends AstItemVisitor {
       deprecatedMessage: astStructuredType.inheritedDeprecatedMessage || [],
       summary: astStructuredType.documentation.summary || [],
       remarks: astStructuredType.documentation.remarks || [],
+      examples: astStructuredType.documentation.examples || [],
       isBeta: astStructuredType.inheritedReleaseTag === ReleaseTag.Beta
     };
 
@@ -130,6 +131,7 @@ export class ApiJsonGenerator extends AstItemVisitor {
       deprecatedMessage: astEnum.inheritedDeprecatedMessage || [],
       summary: astEnum.documentation.summary || [],
       remarks: astEnum.documentation.remarks || [],
+      examples: astEnum.documentation.examples || [],
       isBeta: astEnum.inheritedReleaseTag === ReleaseTag.Beta
     };
     refObject![astEnum.name] = enumNode;
@@ -156,6 +158,7 @@ export class ApiJsonGenerator extends AstItemVisitor {
       deprecatedMessage: astEnumValue.inheritedDeprecatedMessage || [],
       summary: astEnumValue.documentation.summary || [],
       remarks: astEnumValue.documentation.remarks || [],
+      examples: astEnumValue.documentation.examples || [],
       isBeta: astEnumValue.inheritedReleaseTag === ReleaseTag.Beta
     };
   }
@@ -178,6 +181,7 @@ export class ApiJsonGenerator extends AstItemVisitor {
       deprecatedMessage: astFunction.inheritedDeprecatedMessage || [],
       summary: astFunction.documentation.summary || [],
       remarks: astFunction.documentation.remarks || [],
+      examples: astFunction.documentation.examples || [],
       isBeta: astFunction.inheritedReleaseTag === ReleaseTag.Beta
     };
 
@@ -190,6 +194,7 @@ export class ApiJsonGenerator extends AstItemVisitor {
     refObject!['name'] = astPackage.name;
     refObject!['summary'] = astPackage.documentation.summary;
     refObject!['remarks'] = astPackage.documentation.remarks;
+    refObject!['examples'] = astPackage.documentation.examples;
     /* tslint:enable:no-string-literal */
 
     const membersNode: Object = {};
@@ -215,6 +220,7 @@ export class ApiJsonGenerator extends AstItemVisitor {
       deprecatedMessage: astNamespace.inheritedDeprecatedMessage || [],
       summary: astNamespace.documentation.summary || [],
       remarks: astNamespace.documentation.remarks || [],
+      examples: astNamespace.documentation.examples || [],
       isBeta: astNamespace.inheritedReleaseTag === ReleaseTag.Beta,
       exports: membersNode
     };
@@ -249,6 +255,7 @@ export class ApiJsonGenerator extends AstItemVisitor {
       deprecatedMessage: astProperty.inheritedDeprecatedMessage || [],
       summary: astProperty.documentation.summary || [],
       remarks: astProperty.documentation.remarks || [],
+      examples: astProperty.documentation.examples || [],
       isBeta: astProperty.inheritedReleaseTag === ReleaseTag.Beta,
       isSealed: !!astProperty.documentation.isSealed,
       isVirtual: !!astProperty.documentation.isVirtual,
@@ -268,6 +275,7 @@ export class ApiJsonGenerator extends AstItemVisitor {
       deprecatedMessage: astModuleVariable.inheritedDeprecatedMessage || [],
       summary: astModuleVariable.documentation.summary || [],
       remarks: astModuleVariable.documentation.remarks || [],
+      examples: astModuleVariable.documentation.examples || [],
       isBeta: astModuleVariable.inheritedReleaseTag === ReleaseTag.Beta
     };
 
@@ -287,7 +295,8 @@ export class ApiJsonGenerator extends AstItemVisitor {
         parameters: this._createParameters(astMethod),
         deprecatedMessage: astMethod.inheritedDeprecatedMessage || [],
         summary: astMethod.documentation.summary || [],
-        remarks: astMethod.documentation.remarks || []
+        remarks: astMethod.documentation.remarks || [],
+        examples: astMethod.documentation.examples || []
       };
     } else {
       const returnValueNode: IApiReturnValue = {
@@ -306,6 +315,7 @@ export class ApiJsonGenerator extends AstItemVisitor {
         deprecatedMessage: astMethod.inheritedDeprecatedMessage || [],
         summary: astMethod.documentation.summary || [],
         remarks: astMethod.documentation.remarks || [],
+        examples: astMethod.documentation.examples || [],
         isBeta: astMethod.inheritedReleaseTag === ReleaseTag.Beta,
         isSealed: !!astMethod.documentation.isSealed,
         isVirtual: !!astMethod.documentation.isVirtual,

common/changes/@microsoft/api-extractor/better-jsdoc-tag_2018-07-18-23-24.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "Add support to AEDoc for the \"@example\" tag.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor",
+  "email": "[email protected]"
+}

common/reviews/api/api-extractor.api.ts

@@ -37,6 +37,8 @@ interface IApiBaseDefinition {
   // (undocumented)
   deprecatedMessage?: MarkupBasicElement[];
   // (undocumented)
+  examples: MarkupStructuredElement[][];
+  // (undocumented)
   isBeta: boolean;
   kind: string;
   // (undocumented)
@@ -134,6 +136,8 @@ interface IApiNamespace extends IApiBaseDefinition {
 interface IApiPackage {
   // (undocumented)
   deprecatedMessage?: MarkupBasicElement[];
+  // (undocumented)
+  examples: MarkupStructuredElement[][];
   exports: IApiNameMap<ApiItem>;
   isBeta: boolean;
   kind: 'package';