[api-documenter] Support linked types for markdown output

apps/api-documenter/src/documenters/MarkdownDocumenter.ts

@@ -1,8 +1,9 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import * as path from 'path';
+/* eslint max-lines: "off" */
 
+import * as path from 'path';
 import {
   PackageName,
   FileSystem,
@@ -39,7 +40,9 @@ import {
   ApiParameterListMixin,
   ApiReturnTypeMixin,
   ApiDeclaredItem,
-  ApiNamespace
+  ApiNamespace,
+  ExcerptTokenKind,
+  IResolveDeclarationReferenceResult
 } from '@microsoft/api-extractor-model';
 
 import { CustomDocNodes } from '../nodes/CustomDocNodeKind';
@@ -103,7 +106,7 @@ export class MarkdownDocumenter {
     this._writeApiItemPage(this._apiModel);
 
     if (this._pluginLoader.markdownDocumenterFeature) {
-      this._pluginLoader.markdownDocumenterFeature.onFinished({ });
+      this._pluginLoader.markdownDocumenterFeature.onFinished({});
     }
   }
 
@@ -162,7 +165,7 @@ export class MarkdownDocumenter {
     }
 
     if (ApiReleaseTagMixin.isBaseClassOf(apiItem)) {
-      if (apiItem.releaseTag === ReleaseTag.Beta)  {
+      if (apiItem.releaseTag === ReleaseTag.Beta) {
         this._writeBetaWarning(output);
       }
     }
@@ -196,7 +199,7 @@ export class MarkdownDocumenter {
       if (apiItem.excerpt.text.length > 0) {
         output.appendNode(
           new DocParagraph({ configuration }, [
-            new DocEmphasisSpan({ configuration, bold: true}, [
+            new DocEmphasisSpan({ configuration, bold: true }, [
               new DocPlainText({ configuration, text: 'Signature:' })
             ])
           ])
@@ -257,7 +260,7 @@ export class MarkdownDocumenter {
     }
 
     if (appendRemarks) {
-    this._writeRemarksSection(output, apiItem);
+      this._writeRemarksSection(output, apiItem);
     }
 
     const filename: string = path.join(this._outputFolder, this._getFilenameForApiItem(apiItem));
@@ -346,8 +349,9 @@ export class MarkdownDocumenter {
   private _writeModelTable(output: DocSection, apiModel: ApiModel): void {
     const configuration: TSDocConfiguration = this._tsdocConfiguration;
 
-    const packagesTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Package', 'Description' ]
+    const packagesTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Package', 'Description']
     });
 
     for (const apiMember of apiModel.members) {
@@ -377,32 +381,39 @@ export class MarkdownDocumenter {
   private _writePackageOrNamespaceTables(output: DocSection, apiContainer: ApiPackage | ApiNamespace): void {
     const configuration: TSDocConfiguration = this._tsdocConfiguration;
 
-    const classesTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Class', 'Description' ]
+    const classesTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Class', 'Description']
     });
 
-    const enumerationsTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Enumeration', 'Description' ]
+    const enumerationsTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Enumeration', 'Description']
     });
 
-    const functionsTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Function', 'Description' ]
+    const functionsTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Function', 'Description']
     });
 
-    const interfacesTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Interface', 'Description' ]
+    const interfacesTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Interface', 'Description']
     });
 
-    const namespacesTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Namespace', 'Description' ]
+    const namespacesTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Namespace', 'Description']
     });
 
-    const variablesTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Variable', 'Description' ]
+    const variablesTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Variable', 'Description']
     });
 
-    const typeAliasesTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Type Alias', 'Description' ]
+    const typeAliasesTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Type Alias', 'Description']
     });
 
     const apiMembers: ReadonlyArray<ApiItem> = apiContainer.kind === ApiItemKind.Package ?
@@ -495,20 +506,24 @@ export class MarkdownDocumenter {
   private _writeClassTables(output: DocSection, apiClass: ApiClass): void {
     const configuration: TSDocConfiguration = this._tsdocConfiguration;
 
-    const eventsTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Property', 'Modifiers', 'Type', 'Description' ]
+    const eventsTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Property', 'Modifiers', 'Type', 'Description']
     });
 
-    const constructorsTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Constructor', 'Modifiers', 'Description' ]
+    const constructorsTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Constructor', 'Modifiers', 'Description']
     });
 
-    const propertiesTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Property', 'Modifiers', 'Type', 'Description' ]
+    const propertiesTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Property', 'Modifiers', 'Type', 'Description']
     });
 
-    const methodsTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Method', 'Modifiers', 'Description' ]
+    const methodsTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Method', 'Modifiers', 'Description']
     });
 
     for (const apiMember of apiClass.members) {
@@ -594,8 +609,9 @@ export class MarkdownDocumenter {
   private _writeEnumTables(output: DocSection, apiEnum: ApiEnum): void {
     const configuration: TSDocConfiguration = this._tsdocConfiguration;
 
-    const enumMembersTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Member', 'Value', 'Description' ]
+    const enumMembersTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Member', 'Value', 'Description']
     });
 
     for (const apiEnumMember of apiEnum.members) {
@@ -631,16 +647,19 @@ export class MarkdownDocumenter {
   private _writeInterfaceTables(output: DocSection, apiClass: ApiInterface): void {
     const configuration: TSDocConfiguration = this._tsdocConfiguration;
 
-    const eventsTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Property', 'Type', 'Description' ]
+    const eventsTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Property', 'Type', 'Description']
     });
 
-    const propertiesTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Property', 'Type', 'Description' ]
+    const propertiesTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Property', 'Type', 'Description']
     });
 
-    const methodsTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Method', 'Description' ]
+    const methodsTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Method', 'Description']
     });
 
     for (const apiMember of apiClass.members) {
@@ -707,29 +726,27 @@ export class MarkdownDocumenter {
   private _writeParameterTables(output: DocSection, apiParameterListMixin: ApiParameterListMixin): void {
     const configuration: TSDocConfiguration = this._tsdocConfiguration;
 
-    const parametersTable: DocTable = new DocTable({ configuration,
-      headerTitles: [ 'Parameter', 'Type', 'Description' ]
+    const parametersTable: DocTable = new DocTable({
+      configuration,
+      headerTitles: ['Parameter', 'Type', 'Description']
     });
-
     for (const apiParameter of apiParameterListMixin.parameters) {
-      const parameterDescription: DocSection = new DocSection({ configuration } );
+      const parameterDescription: DocSection = new DocSection({ configuration });
       if (apiParameter.tsdocParamBlock) {
         this._appendSection(parameterDescription, apiParameter.tsdocParamBlock.content);
       }
 
       parametersTable.addRow(
         new DocTableRow({ configuration }, [
-          new DocTableCell({configuration}, [
+          new DocTableCell({ configuration }, [
             new DocParagraph({ configuration }, [
               new DocPlainText({ configuration, text: apiParameter.name })
             ])
           ]),
-          new DocTableCell({configuration}, [
-            new DocParagraph({ configuration }, [
-              new DocCodeSpan({ configuration, code: apiParameter.parameterTypeExcerpt.text })
-            ])
+          new DocTableCell({ configuration }, [
+            this._createParagraphForTypeExcerpt(apiParameter.parameterTypeExcerpt)
           ]),
-          new DocTableCell({configuration}, parameterDescription.nodes)
+          new DocTableCell({ configuration }, parameterDescription.nodes)
         ])
       );
     }
@@ -743,16 +760,14 @@ export class MarkdownDocumenter {
       const returnTypeExcerpt: Excerpt = apiParameterListMixin.returnTypeExcerpt;
       output.appendNode(
         new DocParagraph({ configuration }, [
-          new DocEmphasisSpan({ configuration, bold: true}, [
+          new DocEmphasisSpan({ configuration, bold: true }, [
             new DocPlainText({ configuration, text: 'Returns:' })
           ])
         ])
       );
 
       output.appendNode(
-        new DocParagraph({ configuration }, [
-          new DocCodeSpan({ configuration, code: returnTypeExcerpt.text.trim() || '(not declared)' })
-        ])
+        this._createParagraphForTypeExcerpt(returnTypeExcerpt)
       );
 
       if (apiParameterListMixin instanceof ApiDocumentedItem) {
@@ -763,6 +778,44 @@ export class MarkdownDocumenter {
     }
   }
 
+  private _createParagraphForTypeExcerpt(excerpt: Excerpt): DocParagraph {
+    const configuration: TSDocConfiguration = this._tsdocConfiguration;
+
+    const paragraph: DocParagraph = new DocParagraph({ configuration });
+
+    if (!excerpt.text.trim()) {
+      paragraph.appendNode(new DocPlainText({ configuration, text: '(not declared)' }));
+    } else {
+      for (const token of excerpt.spannedTokens) {
+        // Markdown doesn't provide a standardized syntax for hyperlinks inside code spans, so we will render
+        // the type expression as DocPlainText.  Instead of creating multiple DocParagraphs, we can simply
+        // discard any newlines and let the renderer do normal word-wrapping.
+        const unwrappedTokenText: string = token.text.replace(/[\r\n]+/g, ' ');
+
+        // If it's hyperlinkable, then append a DocLinkTag
+        if (token.kind === ExcerptTokenKind.Reference && token.canonicalReference) {
+          const apiItemResult: IResolveDeclarationReferenceResult = this._apiModel.resolveDeclarationReference(
+            token.canonicalReference, undefined);
+
+          if (apiItemResult.resolvedApiItem) {
+            paragraph.appendNode(new DocLinkTag({
+              configuration,
+              tagName: '@link',
+              linkText: unwrappedTokenText,
+              urlDestination: this._getLinkFilenameForApiItem(apiItemResult.resolvedApiItem)
+            }));
+            continue;
+          }
+        }
+
+        // Otherwise append non-hyperlinked text
+        paragraph.appendNode(new DocPlainText({ configuration, text: unwrappedTokenText }));
+      }
+    }
+
+    return paragraph;
+  }
+
   private _createTitleCell(apiItem: ApiItem): DocTableCell {
     const configuration: TSDocConfiguration = this._tsdocConfiguration;
 
@@ -830,7 +883,9 @@ export class MarkdownDocumenter {
     const section: DocSection = new DocSection({ configuration });
 
     if (apiItem instanceof ApiPropertyItem) {
-      section.appendNodeInParagraph(new DocCodeSpan({ configuration, code: apiItem.propertyTypeExcerpt.text }));
+      section.appendNode(
+        this._createParagraphForTypeExcerpt(apiItem.propertyTypeExcerpt)
+      );
     }
 
     return new DocTableCell({ configuration }, section.nodes);

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

@@ -776,9 +776,7 @@ export class YamlDocumenter {
   }
 
   private _renderType(contextUid: DeclarationReference, typeExcerpt: Excerpt): string {
-    const excerptTokens: ExcerptToken[] = typeExcerpt.tokens.slice(
-      typeExcerpt.tokenRange.startIndex,
-      typeExcerpt.tokenRange.endIndex);
+    const excerptTokens: ExcerptToken[] = [...typeExcerpt.spannedTokens]; // copy the read-only array
 
     if (excerptTokens.length === 0) {
       return '';