From 0b37ac54d9aaf9715fe3ce54eed86dc4a25e5af6 Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Sat, 2 May 2020 22:50:25 -0700
Subject: [PATCH] Render hyperlinks using DocPlainText instead of DocCodeSpan

---
 .../src/documenters/MarkdownDocumenter.ts        | 16 ++++++++++++----
 ...cumenter-test.docbaseclass._constructor__1.md |  2 +-
 ...ocumenter-test.docclass1.deprecatedexample.md |  2 +-
 ...-documenter-test.docclass1.examplefunction.md |  6 +++---
 ...ocumenter-test.docclass1.examplefunction_1.md |  4 ++--
 ...menter-test.docclass1.interestingedgecases.md |  2 +-
 .../markdown/api-documenter-test.docclass1.md    |  4 ++--
 ...i-documenter-test.docclass1.sumwithexample.md |  6 +++---
 ...api-documenter-test.docclass1.tableexample.md |  2 +-
 .../api-documenter-test.examplefunction.md       |  2 +-
 ...nter-test.idocinterface2.deprecatedexample.md |  2 +-
 .../api-documenter-test.idocinterface3.md        |  6 +++---
 .../api-documenter-test.idocinterface4.md        |  8 ++++----
 .../api-documenter-test.idocinterface5.md        |  2 +-
 ...test.idocinterface6.genericreferencemethod.md |  4 ++--
 .../api-documenter-test.idocinterface6.md        | 12 ++++++------
 ...ternamespace.innernamespace.nestedfunction.md |  4 ++--
 ...api-documenter-test.systemevent.addhandler.md |  4 ++--
 .../type-link-pr_2020-04-29-16-26.json           |  2 +-
 19 files changed, 49 insertions(+), 41 deletions(-)

diff --git a/apps/api-documenter/src/documenters/MarkdownDocumenter.ts b/apps/api-documenter/src/documenters/MarkdownDocumenter.ts
index ce56fc88876..aaa9a15ccba 100644
--- a/apps/api-documenter/src/documenters/MarkdownDocumenter.ts
+++ b/apps/api-documenter/src/documenters/MarkdownDocumenter.ts
@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+/* eslint max-lines: "off" */
+
 import * as path from 'path';
 import {
   PackageName,
@@ -783,7 +785,7 @@ export class MarkdownDocumenter {
     const paragraph: DocParagraph = new DocParagraph({ configuration });
 
     if (!excerpt.text.trim()) {
-      paragraph.appendNode(new DocCodeSpan({ configuration, code: '(not declared)' }));
+      paragraph.appendNode(new DocPlainText({ configuration, text: '(not declared)' }));
     } else {
       // TODO: Add a helper method to Excerpt to solve this problem
       const excerptTokens: ExcerptToken[] = excerpt.tokens.slice(
@@ -791,7 +793,12 @@ export class MarkdownDocumenter {
         excerpt.tokenRange.endIndex);
 
       for (const token of excerptTokens) {
-        // If it's hyperlinkable, then append a hyperlink node
+        // 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);
@@ -800,14 +807,15 @@ export class MarkdownDocumenter {
             paragraph.appendNode(new DocLinkTag({
               configuration,
               tagName: '@link',
-              linkText: token.text,
+              linkText: unwrappedTokenText,
               urlDestination: this._getLinkFilenameForApiItem(apiItemResult.resolvedApiItem)
             }));
             continue;
           }
         }
+
         // Otherwise append non-hyperlinked text
-        paragraph.appendNode(new DocCodeSpan({ configuration, code: token.text }));
+        paragraph.appendNode(new DocPlainText({ configuration, text: unwrappedTokenText }));
       }
     }
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docbaseclass._constructor__1.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docbaseclass._constructor__1.md
index a8380b80c70..152500bd6ed 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docbaseclass._constructor__1.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docbaseclass._constructor__1.md
@@ -16,5 +16,5 @@ constructor(x: number);
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  x | <code>number</code> |  |
+|  x | number |  |
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.deprecatedexample.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.deprecatedexample.md
index 165f827a2f1..3572fc89d0e 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.deprecatedexample.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.deprecatedexample.md
@@ -16,5 +16,5 @@ deprecatedExample(): void;
 ```
 <b>Returns:</b>
 
-`void`
+void
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.examplefunction.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.examplefunction.md
index 661fb617adc..c081fa0be54 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.examplefunction.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.examplefunction.md
@@ -16,12 +16,12 @@ exampleFunction(a: string, b: string): string;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  a | <code>string</code> | the first string |
-|  b | <code>string</code> | the second string |
+|  a | string | the first string |
+|  b | string | the second string |
 
 <b>Returns:</b>
 
-`string`
+string
 
 ## Exceptions
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.examplefunction_1.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.examplefunction_1.md
index a54d37c8548..498b44a3568 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.examplefunction_1.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.examplefunction_1.md
@@ -16,9 +16,9 @@ exampleFunction(x: number): number;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  x | <code>number</code> | the number |
+|  x | number | the number |
 
 <b>Returns:</b>
 
-`number`
+number
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.interestingedgecases.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.interestingedgecases.md
index 0ab1e611784..dac3180381c 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.interestingedgecases.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.interestingedgecases.md
@@ -15,5 +15,5 @@ interestingEdgeCases(): void;
 ```
 <b>Returns:</b>
 
-`void`
+void
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md
index 70d6506fbf9..4fa249aaba3 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md
@@ -32,9 +32,9 @@ The constructor for this class is marked as internal. Third-party code should no
 
 |  Property | Modifiers | Type | Description |
 |  --- | --- | --- | --- |
-|  [readonlyProperty](./api-documenter-test.docclass1.readonlyproperty.md) |  | <code>string</code> |  |
+|  [readonlyProperty](./api-documenter-test.docclass1.readonlyproperty.md) |  | string |  |
 |  [regularProperty](./api-documenter-test.docclass1.regularproperty.md) |  | [SystemEvent](./api-documenter-test.systemevent.md) | This is a regular property that happens to use the SystemEvent type. |
-|  [writeableProperty](./api-documenter-test.docclass1.writeableproperty.md) |  | <code>string</code> |  |
+|  [writeableProperty](./api-documenter-test.docclass1.writeableproperty.md) |  | string |  |
 
 ## Methods
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.sumwithexample.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.sumwithexample.md
index 8ea932a1c3b..e7c51b3ac5e 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.sumwithexample.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.sumwithexample.md
@@ -16,12 +16,12 @@ static sumWithExample(x: number, y: number): number;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  x | <code>number</code> | the first number to add |
-|  y | <code>number</code> | the second number to add |
+|  x | number | the first number to add |
+|  y | number | the second number to add |
 
 <b>Returns:</b>
 
-`number`
+number
 
 the sum of the two numbers
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.tableexample.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.tableexample.md
index 3b197db94e9..994c0c00f8e 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.tableexample.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.tableexample.md
@@ -13,7 +13,7 @@ tableExample(): void;
 ```
 <b>Returns:</b>
 
-`void`
+void
 
 ## Remarks
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.examplefunction.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.examplefunction.md
index 1a583e2ad13..f86960f8be8 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.examplefunction.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.examplefunction.md
@@ -17,7 +17,7 @@ export declare function exampleFunction(x: ExampleTypeAlias, y: number): IDocInt
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  x | [ExampleTypeAlias](./api-documenter-test.exampletypealias.md) | an API item that should get hyperlinked |
-|  y | <code>number</code> | a system type that should NOT get hyperlinked |
+|  y | number | a system type that should NOT get hyperlinked |
 
 <b>Returns:</b>
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface2.deprecatedexample.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface2.deprecatedexample.md
index 8fc8a3fe71c..08812d228e5 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface2.deprecatedexample.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface2.deprecatedexample.md
@@ -16,5 +16,5 @@ deprecatedExample(): void;
 ```
 <b>Returns:</b>
 
-`void`
+void
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface3.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface3.md
index 28895d133be..c3a585948cf 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface3.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface3.md
@@ -17,9 +17,9 @@ export interface IDocInterface3
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  ["\[not.a.symbol\]"](./api-documenter-test.idocinterface3.__not.a.symbol__.md) | <code>string</code> | An identifier that does needs quotes. It misleadingly looks like an ECMAScript symbol. |
-|  [\[EcmaSmbols.example\]](./api-documenter-test.idocinterface3._ecmasmbols.example_.md) | <code>string</code> | ECMAScript symbol |
-|  [redundantQuotes](./api-documenter-test.idocinterface3.redundantquotes.md) | <code>string</code> | A quoted identifier with redundant quotes. |
+|  ["\[not.a.symbol\]"](./api-documenter-test.idocinterface3.__not.a.symbol__.md) | string | An identifier that does needs quotes. It misleadingly looks like an ECMAScript symbol. |
+|  [\[EcmaSmbols.example\]](./api-documenter-test.idocinterface3._ecmasmbols.example_.md) | string | ECMAScript symbol |
+|  [redundantQuotes](./api-documenter-test.idocinterface3.redundantquotes.md) | string | A quoted identifier with redundant quotes. |
 
 ## Methods
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface4.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface4.md
index 4f78bdd2940..0338865b6fb 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface4.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface4.md
@@ -17,8 +17,8 @@ export interface IDocInterface4
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [Context](./api-documenter-test.idocinterface4.context.md) | <code>({ children }: {</code><br/><code>        children: string;</code><br/><code>    }) =&gt; boolean</code> | Test newline rendering when code blocks are used in tables |
-|  [generic](./api-documenter-test.idocinterface4.generic.md) | [Generic](./api-documenter-test.generic.md)<code>&lt;number&gt;</code> | make sure html entities are escaped in tables. |
-|  [numberOrFunction](./api-documenter-test.idocinterface4.numberorfunction.md) | <code>number &#124; (() =&gt; number)</code> | a union type with a function |
-|  [stringOrNumber](./api-documenter-test.idocinterface4.stringornumber.md) | <code>string &#124; number</code> | a union type |
+|  [Context](./api-documenter-test.idocinterface4.context.md) | ({ children }: { children: string; }) =&gt; boolean | Test newline rendering when code blocks are used in tables |
+|  [generic](./api-documenter-test.idocinterface4.generic.md) | [Generic](./api-documenter-test.generic.md)<!-- -->&lt;number&gt; | make sure html entities are escaped in tables. |
+|  [numberOrFunction](./api-documenter-test.idocinterface4.numberorfunction.md) | number \| (() =&gt; number) | a union type with a function |
+|  [stringOrNumber](./api-documenter-test.idocinterface4.stringornumber.md) | string \| number | a union type |
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface5.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface5.md
index 8e5fe1396f3..687b39f2867 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface5.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface5.md
@@ -16,5 +16,5 @@ export interface IDocInterface5
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [regularProperty](./api-documenter-test.idocinterface5.regularproperty.md) | <code>string</code> | Property of type string that does something |
+|  [regularProperty](./api-documenter-test.idocinterface5.regularproperty.md) | string | Property of type string that does something |
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface6.genericreferencemethod.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface6.genericreferencemethod.md
index a1bacf13445..5aafced4331 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface6.genericreferencemethod.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface6.genericreferencemethod.md
@@ -14,9 +14,9 @@ genericReferenceMethod<T>(x: T): T;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  x | <code>T</code> |  |
+|  x | T |  |
 
 <b>Returns:</b>
 
-`T`
+T
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface6.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface6.md
index a77a415ddf1..bc4e5bc899e 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface6.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface6.md
@@ -16,12 +16,12 @@ export interface IDocInterface6
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [arrayProperty](./api-documenter-test.idocinterface6.arrayproperty.md) | [IDocInterface1](./api-documenter-test.idocinterface1.md)<code>[]</code> |  |
-|  [intersectionProperty](./api-documenter-test.idocinterface6.intersectionproperty.md) | [IDocInterface1](./api-documenter-test.idocinterface1.md)<code> &amp; </code>[IDocInterface2](./api-documenter-test.idocinterface2.md) |  |
-|  [regularProperty](./api-documenter-test.idocinterface6.regularproperty.md) | <code>number</code> | Property of type number that does something |
-|  [tupleProperty](./api-documenter-test.idocinterface6.tupleproperty.md) | <code>[</code>[IDocInterface1](./api-documenter-test.idocinterface1.md)<code>, </code>[IDocInterface2](./api-documenter-test.idocinterface2.md)<code>]</code> |  |
-|  [typeReferenceProperty](./api-documenter-test.idocinterface6.typereferenceproperty.md) | [Generic](./api-documenter-test.generic.md)<code>&lt;</code>[IDocInterface1](./api-documenter-test.idocinterface1.md)<code>&gt;</code> |  |
-|  [unionProperty](./api-documenter-test.idocinterface6.unionproperty.md) | [IDocInterface1](./api-documenter-test.idocinterface1.md)<code> &#124; </code>[IDocInterface2](./api-documenter-test.idocinterface2.md) |  |
+|  [arrayProperty](./api-documenter-test.idocinterface6.arrayproperty.md) | [IDocInterface1](./api-documenter-test.idocinterface1.md)<!-- -->\[\] |  |
+|  [intersectionProperty](./api-documenter-test.idocinterface6.intersectionproperty.md) | [IDocInterface1](./api-documenter-test.idocinterface1.md) &amp; [IDocInterface2](./api-documenter-test.idocinterface2.md) |  |
+|  [regularProperty](./api-documenter-test.idocinterface6.regularproperty.md) | number | Property of type number that does something |
+|  [tupleProperty](./api-documenter-test.idocinterface6.tupleproperty.md) | \[[IDocInterface1](./api-documenter-test.idocinterface1.md)<!-- -->, [IDocInterface2](./api-documenter-test.idocinterface2.md)<!-- -->\] |  |
+|  [typeReferenceProperty](./api-documenter-test.idocinterface6.typereferenceproperty.md) | [Generic](./api-documenter-test.generic.md)<!-- -->&lt;[IDocInterface1](./api-documenter-test.idocinterface1.md)<!-- -->&gt; |  |
+|  [unionProperty](./api-documenter-test.idocinterface6.unionproperty.md) | [IDocInterface1](./api-documenter-test.idocinterface1.md) \| [IDocInterface2](./api-documenter-test.idocinterface2.md) |  |
 
 ## Methods
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.outernamespace.innernamespace.nestedfunction.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.outernamespace.innernamespace.nestedfunction.md
index 6b46ca54670..3ba952009e5 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.outernamespace.innernamespace.nestedfunction.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.outernamespace.innernamespace.nestedfunction.md
@@ -16,9 +16,9 @@ function nestedFunction(x: number): number;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  x | <code>number</code> |  |
+|  x | number |  |
 
 <b>Returns:</b>
 
-`number`
+number
 
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.systemevent.addhandler.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.systemevent.addhandler.md
index a73ed0df48f..cafc021ee8e 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.systemevent.addhandler.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.systemevent.addhandler.md
@@ -16,9 +16,9 @@ addHandler(handler: () => void): void;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  handler | <code>() =&gt; void</code> |  |
+|  handler | () =&gt; void |  |
 
 <b>Returns:</b>
 
-`void`
+void
 
diff --git a/common/changes/@microsoft/api-documenter/type-link-pr_2020-04-29-16-26.json b/common/changes/@microsoft/api-documenter/type-link-pr_2020-04-29-16-26.json
index 3249b2ab0eb..2278b598bcb 100644
--- a/common/changes/@microsoft/api-documenter/type-link-pr_2020-04-29-16-26.json
+++ b/common/changes/@microsoft/api-documenter/type-link-pr_2020-04-29-16-26.json
@@ -3,7 +3,7 @@
     {
       "packageName": "@microsoft/api-documenter",
       "comment": "Support linked types in type cells and return fields",
-      "type": "patch"
+      "type": "minor"
     }
   ],
   "packageName": "@microsoft/api-documenter",