If the link text is omitted, automatically generate it based on the ApiItem name

pgonzal · pgonzal · commit 83a904a999d2 · 2018-11-09T13:54:41.000-08:00
diff --git a/apps/api-documenter/src/markdown/CustomMarkdownEmitter.ts b/apps/api-documenter/src/markdown/CustomMarkdownEmitter.ts
@@ -1,8 +1,10 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import * as colors from 'colors';
+
 import {
-  DocNode
+  DocNode, DocLinkTag, StringBuilder
 } from '@microsoft/tsdoc';
 import { CustomDocNodeKind } from '../nodes/CustomDocNodeKind';
 import { DocHeading } from '../nodes/DocHeading';
@@ -11,9 +13,27 @@ import { DocTable } from '../nodes/DocTable';
 import { DocTableCell } from '../nodes/DocTableCell';
 import { DocEmphasisSpan } from '../nodes/DocEmphasisSpan';
 import { SimpleWriter } from './SimpleWriter';
-import { MarkdownEmitter, IMarkdownEmitterContext } from './MarkdownEmitter';
+import { MarkdownEmitter, IMarkdownEmitterContext, IMarkdownEmitterOptions } from './MarkdownEmitter';
+import { ApiModel, IResolveDeclarationReferenceResult, ApiItem } from '@microsoft/api-extractor';
+
+export interface ICustomMarkdownEmitterOptions extends IMarkdownEmitterOptions {
+  contextApiItem: ApiItem | undefined;
+
+  onGetFilenameForApiItem: (apiItem: ApiItem) => string | undefined;
+}
 
 export class CustomMarkdownEmitter extends MarkdownEmitter {
+  private _apiModel: ApiModel;
+
+  public constructor (apiModel: ApiModel) {
+    super();
+
+    this._apiModel = apiModel;
+  }
+
+  public emit(stringBuilder: StringBuilder, docNode: DocNode, options: ICustomMarkdownEmitterOptions): string {
+    return super.emit(stringBuilder, docNode, options);
+  }
 
   /** @override */
   protected writeNode(docNode: DocNode, context: IMarkdownEmitterContext): void {
@@ -118,4 +138,38 @@ export class CustomMarkdownEmitter extends MarkdownEmitter {
     }
   }
 
+  /** @override */
+  protected writeLinkTagWithCodeDestination(docLinkTag: DocLinkTag,
+    context: IMarkdownEmitterContext<ICustomMarkdownEmitterOptions>): void {
+
+    const options: ICustomMarkdownEmitterOptions = context.options;
+
+    const result: IResolveDeclarationReferenceResult
+      = this._apiModel.resolveDeclarationReference(docLinkTag.codeDestination!, options.contextApiItem);
+
+    if (result.resolvedApiItem) {
+      const filename: string | undefined = options.onGetFilenameForApiItem(result.resolvedApiItem);
+
+      if (filename) {
+        let linkText: string = docLinkTag.linkText || '';
+        if (linkText.length === 0) {
+
+          // Generate a name such as Namespace1.Namespace2.MyClass.myMethod()
+          linkText = result.resolvedApiItem.getScopedNameWithinPackage();
+        }
+        if (linkText.length > 0) {
+          const encodedLinkText: string = this.getEscapedText(linkText.replace(/\s+/g, ' '));
+
+          context.writer.write('[');
+          context.writer.write(encodedLinkText);
+          context.writer.write(`](${filename!})`);
+        } else {
+          console.log(colors.red('WARNING: Unable to determine link text'));
+        }
+      }
+    } else if (result.errorMessage) {
+      console.log(colors.red('WARNING: Unable to resolve reference: ' + result.errorMessage));
+    }
+  }
+
 }
diff --git a/apps/api-documenter/src/markdown/MarkdownDocumenter.ts b/apps/api-documenter/src/markdown/MarkdownDocumenter.ts
@@ -6,8 +6,7 @@ import * as path from 'path';
 import {
   PackageName,
   FileSystem,
-  NewlineKind,
-  Colors
+  NewlineKind
 } from '@microsoft/node-core-library';
 import {
   DocSection,
@@ -34,8 +33,7 @@ import {
   ApiStaticMixin,
   ApiResultTypeMixin,
   ApiPropertyItem,
-  ApiFunctionLikeMixin,
-  IResolveDeclarationReferenceResult
+  ApiFunctionLikeMixin
 } from '@microsoft/api-extractor';
 
 import { CustomDocNodes } from '../nodes/CustomDocNodeKind';
@@ -61,7 +59,7 @@ export class MarkdownDocumenter {
   public constructor(docItemSet: ApiModel) {
     this._apiModel = docItemSet;
     this._tsdocConfiguration = CustomDocNodes.configuration;
-    this._markdownEmitter = new CustomMarkdownEmitter();
+    this._markdownEmitter = new CustomMarkdownEmitter(this._apiModel);
   }
 
   public generateFiles(outputFolder: string): void {
@@ -169,23 +167,11 @@ export class MarkdownDocumenter {
     const stringBuilder: StringBuilder = new StringBuilder();
 
     this._markdownEmitter.emit(stringBuilder, output, {
-      onResolveTargetForCodeDestination: (docLinkTag: DocLinkTag) => {
-        if (docLinkTag.codeDestination) {
-          const result: IResolveDeclarationReferenceResult
-            = this._apiModel.resolveDeclarationReference(docLinkTag.codeDestination, apiItem);
-
-          if (result.resolvedApiItem) {
-            // NOTE: GitHub's markdown renderer does not resolve relative hyperlinks correctly
-            // unless they start with "./" or "../".
-            return './' + this._getFilenameForApiItem(result.resolvedApiItem);
-          }
-
-          if (result.errorMessage) {
-            console.log(Colors.red('WARNING: Unable to resolve reference: ' + result.errorMessage));
-          }
-        }
-
-        return undefined;
+      contextApiItem: apiItem,
+      onGetFilenameForApiItem: (apiItemForFilename: ApiItem) => {
+        // NOTE: GitHub's markdown renderer does not resolve relative hyperlinks correctly
+        // unless they start with "./" or "../".
+        return './' + this._getFilenameForApiItem(apiItemForFilename);
       }
     });
 
diff --git a/apps/api-documenter/src/markdown/MarkdownEmitter.ts b/apps/api-documenter/src/markdown/MarkdownEmitter.ts
@@ -20,14 +20,9 @@ import {
 import { SimpleWriter } from './SimpleWriter';
 
 export interface IMarkdownEmitterOptions {
-  /**
-   * Given a DocLinkTag with a codeDestination property, determine the target link that should be emitted
-   * in the "[link text](target URL)" Markdown notation.  If the link cannot be resolved, undefined is returned.
-   */
-  onResolveTargetForCodeDestination: (docLinkTag: DocLinkTag) => string | undefined;
 }
 
-export interface IMarkdownEmitterContext {
+export interface IMarkdownEmitterContext<TOptions = IMarkdownEmitterOptions> {
   writer: SimpleWriter;
   insideTable: boolean;
 
@@ -37,7 +32,7 @@ export interface IMarkdownEmitterContext {
   writingBold: boolean;
   writingItalic: boolean;
 
-  options: IMarkdownEmitterOptions;
+  options: TOptions;
 }
 
 /**
@@ -113,24 +108,13 @@ export class MarkdownEmitter {
       }
       case DocNodeKind.LinkTag: {
         const docLinkTag: DocLinkTag = docNode as DocLinkTag;
-        if (docLinkTag.linkText !== undefined && docLinkTag.linkText.length > 0) {
-          const encodedLinkText: string = this.getEscapedText(docLinkTag.linkText.replace(/\s+/g, ' '));
-          let destination: string | undefined = undefined;
-          if (docLinkTag.codeDestination) {
-            destination = context.options.onResolveTargetForCodeDestination(docLinkTag);
-          } else if (docLinkTag.urlDestination) {
-            destination = docLinkTag.urlDestination;
-          }
-
-          if (destination !== undefined) {
-            writer.write('[');
-            writer.write(encodedLinkText);
-            writer.write(`](${destination})`);
-          } else {
-            writer.write(encodedLinkText);
-          }
+        if (docLinkTag.codeDestination) {
+          this.writeLinkTagWithCodeDestination(docLinkTag, context);
+        } else if (docLinkTag.urlDestination) {
+          this.writeLinkTagWithUrlDestination(docLinkTag, context);
+        } else if (docLinkTag.linkText) {
+          this.writePlainText(docLinkTag.linkText, context);
         }
-
         break;
       }
       case DocNodeKind.Paragraph: {
@@ -184,6 +168,25 @@ export class MarkdownEmitter {
     }
   }
 
+  /** @virtual */
+  protected writeLinkTagWithCodeDestination(docLinkTag: DocLinkTag, context: IMarkdownEmitterContext): void {
+
+    // The subclass needs to implement this to support code destinations
+    throw new Error('writeLinkTagWithCodeDestination()');
+  }
+
+  /** @virtual */
+  protected writeLinkTagWithUrlDestination(docLinkTag: DocLinkTag, context: IMarkdownEmitterContext): void {
+    const linkText: string = docLinkTag.linkText !== undefined ? docLinkTag.linkText
+      : docLinkTag.urlDestination!;
+
+    const encodedLinkText: string = this.getEscapedText(linkText.replace(/\s+/g, ' '));
+
+    context.writer.write('[');
+    context.writer.write(encodedLinkText);
+    context.writer.write(`](${docLinkTag.urlDestination!})`);
+  }
+
   protected writePlainText(text: string, context: IMarkdownEmitterContext): void {
     const writer: SimpleWriter = context.writer;
 
diff --git a/apps/api-documenter/src/markdown/test/CustomMarkdownEmitter.test.ts b/apps/api-documenter/src/markdown/test/CustomMarkdownEmitter.test.ts
@@ -22,6 +22,7 @@ import { DocTable } from '../../nodes/DocTable';
 import { DocTableRow } from '../../nodes/DocTableRow';
 import { DocTableCell } from '../../nodes/DocTableCell';
 import { CustomMarkdownEmitter } from '../CustomMarkdownEmitter';
+import { ApiModel, ApiItem } from '@microsoft/api-extractor';
 
 test('render Markdown from TSDoc', done => {
   const outputFolder: string = FileDiffTest.prepareFolder(__dirname, 'MarkdownPageRenderer');
@@ -197,9 +198,13 @@ test('render Markdown from TSDoc', done => {
 
   const outputFilename: string = path.join(outputFolder, 'ActualOutput.md');
   const stringBuilder: StringBuilder = new StringBuilder();
-  const markdownEmitter: CustomMarkdownEmitter = new CustomMarkdownEmitter();
+  const apiModel: ApiModel = new ApiModel();
+  const markdownEmitter: CustomMarkdownEmitter = new CustomMarkdownEmitter(apiModel);
   markdownEmitter.emit(stringBuilder, output, {
-    onResolveTargetForCodeDestination: (docLinkTag: DocLinkTag) => '#'
+    contextApiItem: undefined,
+    onGetFilenameForApiItem: (apiItem: ApiItem) => {
+      return '#';
+    }
   });
   FileSystem.writeFile(outputFilename, stringBuilder.toString());
 
diff --git a/apps/api-extractor/src/api/model/ApiItem.ts b/apps/api-extractor/src/api/model/ApiItem.ts
@@ -110,6 +110,28 @@ export class ApiItem {
     return hierarchy;
   }
 
+  /**
+   * This returns a scoped name such as `"Namespace1.Namespace2.MyClass.myMember()"`.  It does not include the
+   * package name or entry point.
+   */
+  public getScopedNameWithinPackage(): string {
+    const reversedParts: string[] = [];
+
+    for (let current: ApiItem | undefined = this; current !== undefined; current = current.parent) {
+      if (current.kind === ApiItemKind.EntryPoint) {
+        break;
+      }
+      if (reversedParts.length !== 0) {
+        reversedParts.push('.');
+      } else if (ApiFunctionLikeMixin.isBaseClassOf(current)) { // tslint:disable-line:no-use-before-declare
+        reversedParts.push('()');
+      }
+      reversedParts.push(current.name);
+    }
+
+    return reversedParts.reverse().join('');
+  }
+
   /**
    * If this item is an ApiPackage or has an ApiPackage as one of its parents, then that object is returned.
    * Otherwise undefined is returned.
@@ -135,3 +157,4 @@ export interface IApiItemConstructor extends Constructor<ApiItem>, PropertiesOf<
 // Circular import
 import { Deserializer } from './Deserializer';
 import { ApiPackage } from './ApiPackage';
+import { ApiFunctionLikeMixin } from '../mixins/ApiFunctionLikeMixin';
