Render hyperlinks using DocPlainText instead of DocCodeSpan

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,
@@ -782,10 +784,15 @@ 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 {
       for (const token of excerpt.spannedTokens) {
-        // 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);
@@ -794,14 +801,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 }));
       }
     }
 

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 |  |
 

build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.deprecatedexample.md

@@ -16,5 +16,5 @@ deprecatedExample(): void;
 ```
 <b>Returns:</b>
 
-`void`
+void
 

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
 

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
 

build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.interestingedgecases.md

@@ -15,5 +15,5 @@ interestingEdgeCases(): void;
 ```
 <b>Returns:</b>
 
-`void`
+void
 

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
 

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
 

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
 

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>
 

build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface2.deprecatedexample.md

@@ -16,5 +16,5 @@ deprecatedExample(): void;
 ```
 <b>Returns:</b>
 
-`void`
+void
 

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
 

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 |
 

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 |
 

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
 

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
 

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
 

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