Add support for emitting type parameters to yaml

rbuckton · rbuckton · commit a2a2cf184ffb · 2019-06-08T12:57:28.000-07:00
diff --git a/apps/api-documenter/src/documenters/YamlDocumenter.ts b/apps/api-documenter/src/documenters/YamlDocumenter.ts
@@ -33,7 +33,8 @@ import {
   ApiMethodSignature,
   ApiConstructor,
   ApiFunction,
-  ApiReturnTypeMixin
+  ApiReturnTypeMixin,
+  ApiTypeParameterListMixin
 } from '@microsoft/api-extractor-model';
 
 import {
@@ -328,11 +329,11 @@ export class YamlDocumenter {
         break;
       case ApiItemKind.Class:
         yamlItem.type = 'class';
-        this._populateYamlClassOrInterface(yamlItem, apiItem);
+        this._populateYamlClassOrInterface(yamlItem, apiItem as ApiClass);
         break;
       case ApiItemKind.Interface:
         yamlItem.type = 'interface';
-        this._populateYamlClassOrInterface(yamlItem, apiItem);
+        this._populateYamlClassOrInterface(yamlItem, apiItem as ApiInterface);
         break;
       case ApiItemKind.Method:
       case ApiItemKind.MethodSignature:
@@ -379,7 +380,27 @@ export class YamlDocumenter {
     return yamlItem as IYamlItem;
   }
 
-  private _populateYamlClassOrInterface(yamlItem: Partial<IYamlItem>, apiItem: ApiDocumentedItem): void {
+  private _populateYamlTypeParameters(apiItem: ApiTypeParameterListMixin): IYamlParameter[] {
+    const typeParameters: IYamlParameter[] = [];
+    for (const apiTypeParameter of apiItem.typeParameters) {
+      const typeParameter: IYamlParameter = {
+        id: apiTypeParameter.name
+      };
+
+      if (apiTypeParameter.tsdocTypeParamBlock) {
+        typeParameter.description = this._renderMarkdown(apiTypeParameter.tsdocTypeParamBlock.content, apiItem);
+      }
+
+      if (apiTypeParameter.constraintExcerpt) {
+        typeParameter.type = [ this._linkToUidIfPossible(apiTypeParameter.constraintExcerpt.text) ];
+      }
+
+      typeParameters.push(typeParameter);
+    }
+    return typeParameters;
+  }
+
+  private _populateYamlClassOrInterface(yamlItem: Partial<IYamlItem>, apiItem: ApiClass | ApiInterface): void {
     if (apiItem instanceof ApiClass) {
       if (apiItem.extendsType) {
         yamlItem.extends = [ this._linkToUidIfPossible(apiItem.extendsType.excerpt.text) ];
@@ -397,6 +418,11 @@ export class YamlDocumenter {
           yamlItem.extends.push(this._linkToUidIfPossible(extendsType.excerpt.text));
         }
       }
+
+      const typeParameters: IYamlParameter[] = this._populateYamlTypeParameters(apiItem);
+      if (typeParameters.length) {
+        yamlItem.syntax = { typeParameters };
+      }
     }
 
     if (apiItem.tsdocComment) {
@@ -462,6 +488,14 @@ export class YamlDocumenter {
     if (parameters.length) {
       syntax.parameters = parameters;
     }
+
+    if (ApiTypeParameterListMixin.isBaseClassOf(apiItem)) {
+      const typeParameters: IYamlParameter[] = this._populateYamlTypeParameters(apiItem);
+      if (typeParameters.length) {
+        syntax.typeParameters = typeParameters;
+      }
+    }
+
   }
 
   private _populateYamlProperty(yamlItem: Partial<IYamlItem>, apiItem: ApiPropertyItem): void {
diff --git a/apps/api-documenter/src/yaml/IYamlApiFile.ts b/apps/api-documenter/src/yaml/IYamlApiFile.ts
@@ -112,5 +112,6 @@ export interface IYamlSource {
 export interface IYamlSyntax {
   content?: string;
   parameters?: IYamlParameter[];
+  typeParameters?: IYamlParameter[];
   return?: IYamlReturn;
 }
diff --git a/apps/api-documenter/src/yaml/typescript.schema.json b/apps/api-documenter/src/yaml/typescript.schema.json
@@ -221,6 +221,14 @@
 				"content": {
 					"type": "string"
 				},
+				"typeParameters": {
+					"type": "array",
+					"items": {
+						"$ref": "#/definitions/parameter"
+					},
+					"minItems": 1,
+					"uniqueItems": true
+				},
 				"parameters": {
 					"type": "array",
 					"items": {
diff --git a/build-tests/api-documenter-test/etc/api-documenter-test.api.json b/build-tests/api-documenter-test/etc/api-documenter-test.api.json
@@ -690,16 +690,7 @@
           "releaseTag": "Public",
           "typeParameters": [
             {
-              "kind": "TypeParameter",
-              "canonicalReference": "(T:typeparam)",
-              "docComment": "",
-              "excerptTokens": [
-                {
-                  "kind": "Reference",
-                  "text": "T"
-                }
-              ],
-              "name": "T"
+              "typeParameterName": "T"
             }
           ],
           "name": "Generic",

Original file line number	Diff line number	Diff line change
`@@ -112,5 +112,6 @@ export interface IYamlSource {`
`112`	`112`	`export interface IYamlSyntax {`
`113`	`113`	`content?: string;`
`114`	`114`	`parameters?: IYamlParameter[];`
	`115`	`+ typeParameters?: IYamlParameter[];`
`115`	`116`	`return?: IYamlReturn;`
`116`	`117`	`}`