Generalize MarkdownRenderer to support link resolution

pgonzal · pgonzal · commit 0e3315b2566b · 2018-11-08T15:11:18.000-08:00
diff --git a/apps/api-documenter/src/markdown/MarkdownDocumenter.ts b/apps/api-documenter/src/markdown/MarkdownDocumenter.ts
@@ -164,7 +164,11 @@ export class MarkdownDocumenter {
     const filename: string = path.join(this._outputFolder, this._getFilenameForApiItem(apiItem));
     const stringBuilder: StringBuilder = new StringBuilder();
 
-    MarkdownRenderer.renderNode(stringBuilder, output);
+    MarkdownRenderer.renderNode(stringBuilder, output, {
+      onResolveTargetForCodeDestination: (docLinkTag: DocLinkTag) => {
+        return '#';
+      }
+    });
 
     FileSystem.writeFile(filename, stringBuilder.toString(), {
       convertLineEndings: NewlineKind.CrLf
@@ -417,10 +421,6 @@ export class MarkdownDocumenter {
   private _writeFunctionLikeTables(output: DocSection, apiFunctionLike: ApiFunctionLikeMixin): void {
     const configuration: TSDocConfiguration = this._tsdocConfiguration;
 
-    if (apiFunctionLike.name === 'example') {
-      debugger;
-    }
-
     const parametersTable: DocTable = new DocTable({ configuration,
       headerTitles: [ 'Parameter', 'Type', 'Description' ]
     });
diff --git a/apps/api-documenter/src/utils/MarkdownRenderer.ts b/apps/api-documenter/src/utils/MarkdownRenderer.ts
@@ -92,6 +92,14 @@ class SimpleWriter {
   }
 }
 
+export interface IMarkdownRendererOptions {
+  /**
+   * 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;
+}
+
 interface IRenderContext {
   writer: SimpleWriter;
   insideTable: boolean;
@@ -101,6 +109,8 @@ interface IRenderContext {
 
   writingBold: boolean;
   writingItalic: boolean;
+
+  options: IMarkdownRendererOptions;
 }
 
 /**
@@ -109,7 +119,7 @@ interface IRenderContext {
  */
 export class MarkdownRenderer {
 
-  public static renderNode(stringBuilder: StringBuilder, docNode: DocNode): string {
+  public static renderNode(stringBuilder: StringBuilder, docNode: DocNode, options: IMarkdownRendererOptions): string {
     const writer: SimpleWriter = new SimpleWriter(stringBuilder);
 
     const context: IRenderContext = {
@@ -120,7 +130,9 @@ export class MarkdownRenderer {
       italicRequested: false,
 
       writingBold: false,
-      writingItalic: false
+      writingItalic: false,
+
+      options
     };
 
     MarkdownRenderer._writeNode(docNode, context);
@@ -171,11 +183,24 @@ export class MarkdownRenderer {
       }
       case DocNodeKind.LinkTag: {
         const docLinkTag: DocLinkTag = docNode as DocLinkTag;
-        writer.write('[');
-        if (docLinkTag.linkText !== undefined) {
-          writer.write(docLinkTag.linkText.replace(/\s+/g, ' '));
+        if (docLinkTag.linkText !== undefined && docLinkTag.linkText.length > 0) {
+          const encodedLinkText: string = MarkdownRenderer._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);
+          }
         }
-        writer.write(`](${docLinkTag.urlDestination || ''})`);
+
         break;
       }
       case DocNodeKind.Paragraph: {
diff --git a/apps/api-documenter/src/utils/test/MarkdownRenderer.test.ts b/apps/api-documenter/src/utils/test/MarkdownRenderer.test.ts
@@ -197,7 +197,9 @@ test('render Markdown from TSDoc', done => {
 
   const outputFilename: string = path.join(outputFolder, 'ActualOutput.md');
   const stringBuilder: StringBuilder = new StringBuilder();
-  MarkdownRenderer.renderNode(stringBuilder, output);
+  MarkdownRenderer.renderNode(stringBuilder, output, {
+    onResolveTargetForCodeDestination: (docLinkTag: DocLinkTag) => '#'
+  });
   FileSystem.writeFile(outputFilename, stringBuilder.toString());
 
   FileDiffTest.assertEqual(outputFilename, path.join(__dirname, 'ExpectedOutput.md'));
