[api-documenter] Support linked types for markdown output #1849

Feiyang1 · 2020-04-29T00:58:26Z

Fixes #1611
This adds support for linked types for type cells and return types for markdown output.

I followed @octogonz's recommendation by creating a map in ApiModel to track canonicalReference --> ApiItem, then conditionally creating DocLinkTag for types if the corresponding ApiItem is found in the map.

Let me know if/where tests need to be added. Will be happy to do that.

msftclas · 2020-04-29T00:58:39Z

All CLA requirements met.

octogonz · 2020-04-29T07:17:14Z

Awesome! I'll take a look at this ASAP.

octogonz · 2020-05-02T05:16:19Z

build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface6.md

@@ -17,11 +17,11 @@ export interface IDocInterface6
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [arrayProperty](./api-documenter-test.idocinterface6.arrayproperty.md) | <code>IDocInterface1[]</code> |  |
-|  [intersectionProperty](./api-documenter-test.idocinterface6.intersectionproperty.md) | <code>IDocInterface1 &amp; IDocInterface2</code> |  |
+|  [intersectionProperty](./api-documenter-test.idocinterface6.intersectionproperty.md) | [IDocInterface2](./api-documenter-test.idocinterface2.md) |  |


@Feiyang1 this test case is not being handled properly

octogonz · 2020-05-02T05:16:25Z

build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface6.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>[IDocInterface1, IDocInterface2]</code> |  |
 |  [typeReferenceProperty](./api-documenter-test.idocinterface6.typereferenceproperty.md) | <code>Generic&lt;IDocInterface1&gt;</code> |  |
-|  [unionProperty](./api-documenter-test.idocinterface6.unionproperty.md) | <code>IDocInterface1 &#124; IDocInterface2</code> |  |
+|  [unionProperty](./api-documenter-test.idocinterface6.unionproperty.md) | [IDocInterface2](./api-documenter-test.idocinterface2.md) |  |


@Feiyang1 also this test case is not being handled properly

octogonz · 2020-05-02T05:57:50Z

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

+  private _tryCreateLinkTagForTypeExcerpt(excerpt: Excerpt): DocLinkTag | undefined {
+      const configuration: TSDocConfiguration = this._tsdocConfiguration;
+      // Use the last token, so it works for namespace types, e.g. types.MyType
+      const typeExcerptToken: ExcerptToken = excerpt.tokens[excerpt.tokenRange.endIndex - 1];


@Feiyang1 you need to go loop through the individual tokens and only hyperlink the tokens with ExcerptTokenKind.Reference.

The DocFX/YAML documenter's _renderType() is not a good example to work from, because the YAML file has a weird specialized representation for "complex" types. Whereas for the Markdown documenter, we're just making plain text with some hyperlinks inside.

This means that _tryCreateLinkTagForTypeExcerpt() probably needs to return a DocParagraph instead of a simple DocLinkTag.

Here's a sketch of how to fix that: a12b04b

It might need some tuning to handle different ways that whitespace can end up in the DocCodeSpan parts. I noticed that the original implementation was trim()ing them for some reason. (?)

Hope that helps!

Ah, that makes sense! I didn't think about composite types. Your sketch is very helpful - I copy/pasted it into this PR.

I believe the original implementation trim()s text for return type because it allows to write the one liner that handles both empty string and only whitespace cases. It probably doesn't matter format wise, so I think we should be good without trim()ing.

What do you think?

@Feiyang1 Looking at some examples, I'm thinking maybe we should switch to plain text instead of code blocks for these type excerpts.

Option 1: DocCodeSpan (original approach)

Consider this example generated by your current PR (using DocCodeSpan):

f() function

An example function.

Signature:

export declare function f(a: Apple | Banana, b: Map<Apple, number>, y: string | number, z: Symbol): Apple & Banana;

Parameters

Parameter Type Description

a Apple | Banana two hyperlinkable types

b Map<Apple, number> one hyperlinkable type in a generic type

y string | number

z Symbol

Returns:

Apple&Banana

two hyperlinkable types as the return value

Option 2: DocPlainText

And here's how it would look with DocPlainText:

f() function

An example function.

Signature:

export declare function f(a: Apple | Banana, b: Map<Apple, number>, y: string | number, z: Symbol): Apple & Banana;

Parameters

Parameter Type Description

a Apple | Banana two hyperlinkable types

b Map<Apple, number> one hyperlinkable type in a generic type

y string | number

z Symbol

Returns:

Apple & Banana

two hyperlinkable types as the return value

I think the second way might actually look better. What's your opinion?

Option 3: links inside <code>

A third possibility would be to use markdown links inside <code> tags, like this:

<b>Returns:</b> <code>[Apple](./api-documenter-test.apple.md) & [Banana](./api-documenter-test.banana.md)</code>

GitHub renders it like this:

f() function

An example function.

Signature:

export declare function f(a: Apple | Banana, b: Map<Apple, number>, y: string | number, z: Symbol): Apple & Banana;

Parameters

Parameter Type Description

a Apple | Banana two hyperlinkable types

b Map<Apple, number> one hyperlinkable type in a generic type

y string | number

z Symbol

Returns:

Apple & Banana

two hyperlinkable types as the return value

It's definitely not standard Markdown, but a lot of other popular markdown engines seem to support it:

Marked renders it correctly

markdown-it renders it correctly, but only if the "HTML tags" option is enabled

Kramdown (used by Jekyll) doesn't seem to support this at all

Right now I'm leaning towards Option 2 DocPlainText.

@Feiyang1 here is an implementation of Option 2: Feiyang1#1

I like the output of Option 3, but it's unfortunately not standard markdown. So yeah, Option 2 seems to be the most reasonable choice.

I went ahead and resolved the merge conflict in your PR. Feel free to merge.

…rosoft/tsdoc` library is used

octogonz · 2020-05-06T08:09:46Z

I have regenerated the Rush Stack API Docs using this PR. Definitely looks better! 😁

octogonz · 2020-05-06T17:07:05Z

This fix was published with API Documenter 7.8.0

octogonz · 2020-05-06T17:14:11Z

@Feiyang1 FYI we mentioned you in the announcement: https://twitter.com/rushstack/status/1258082338929434632

Feiyang1 · 2020-05-06T17:33:02Z

Woohoo! Thank you for the thorough feedback, adding tests and writing code directly! api-extractor/api-documenter is a great combo for creating reference docs and other things for Typescript libraries (maybe the best right now). Keep up the good work!

Feiyang1 added 13 commits April 27, 2020 12:55

Make jest work

89f9ab8

debug settup

7fa8d3f

plumbing for rending types as links

94cee00

function parameter types are links now

2f1c6d0

Added apiItemsByCanonicalReference map

3d49789

revert previous implementation

363d013

use the canonical type name

39ef0e1

link for function parameter types and return types

01f29d4

link for interface property types

160913d

get ready for PR

005cbb8

recover launch.json

4398277

format

bedc168

format

1422d1a

Feiyang1 requested review from apostolisms, D4N14L, halfnibble, iclanton, octogonz and sachinjoseph as code owners April 29, 2020 00:58

Feiyang1 and others added 2 commits April 29, 2020 09:27

run rush change

90d70bb

Regenerate api-documenter-test test output

5fdd891

octogonz reviewed May 2, 2020

View reviewed changes

Add a test case for hyperlinked function parameters and return value

6f8e54e

octogonz reviewed May 2, 2020

View reviewed changes

Feiyang1 added 3 commits May 2, 2020 11:37

Handle composite type link properly

93b481c

Update test output

eaf47bb

remove an empty line to make linter happy

ee6769f

Render hyperlinks using DocPlainText instead of DocCodeSpan

0b37ac5

octogonz mentioned this pull request May 3, 2020

Render hyperlinks using DocPlainText instead of DocCodeSpan Feiyang1/rushstack#1

Merged

octogonz and others added 2 commits May 2, 2020 23:37

Fix "TODO" item and add some missing API docs for Excerpt.ts

5edbfaf

Merge branch 'type-link-pr' into type-link-pr-proposal

3535fa6

iclanton changed the title ~~Support linked types for markdown output~~ [api-documenter] Support linked types for markdown output May 4, 2020

octogonz added 2 commits May 6, 2020 00:50

Add a safeguard for a case where an incompatible version of the `@mic…

8e6a8dd

…rosoft/tsdoc` library is used

Update change files

d9b7204

octogonz approved these changes May 6, 2020

View reviewed changes

Merge branch 'type-link-pr' into type-link-pr-proposal

c1893e5

octogonz merged commit 8b1a233 into microsoft:master May 6, 2020

szubster mentioned this pull request Sep 20, 2021

[api-documenter] Type unions are not escaped in markdown #2914

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[api-documenter] Support linked types for markdown output #1849

[api-documenter] Support linked types for markdown output #1849

Feiyang1 commented Apr 29, 2020 •

edited

Loading

msftclas commented Apr 29, 2020 •

edited

Loading

octogonz commented Apr 29, 2020

octogonz May 2, 2020

octogonz May 2, 2020

octogonz May 2, 2020

octogonz May 2, 2020

Feiyang1 May 2, 2020

octogonz May 3, 2020 •

edited

Loading

octogonz May 3, 2020 •

edited

Loading

octogonz May 3, 2020

Feiyang1 May 4, 2020

octogonz commented May 6, 2020

octogonz commented May 6, 2020

octogonz commented May 6, 2020

Feiyang1 commented May 6, 2020

Parameter	Type	Description
a	Apple `\|` Banana	two hyperlinkable types
b	`Map<`Apple`, number>`	one hyperlinkable type in a generic type
y	`string \| number`
z	`Symbol`

Parameter	Type	Description
a	Apple \| Banana	two hyperlinkable types
b	Map<Apple, number>	one hyperlinkable type in a generic type
y	string \| number
z	Symbol

Parameter	Type	Description
a	`Apple \| Banana`	two hyperlinkable types
b	`Map<Apple, number>`	one hyperlinkable type in a generic type
y	`string \| number`
z	`Symbol`

[api-documenter] Support linked types for markdown output #1849

[api-documenter] Support linked types for markdown output #1849

Conversation

Feiyang1 commented Apr 29, 2020 • edited Loading

msftclas commented Apr 29, 2020 • edited Loading

octogonz commented Apr 29, 2020

octogonz May 2, 2020

Choose a reason for hiding this comment

octogonz May 2, 2020

Choose a reason for hiding this comment

octogonz May 2, 2020

Choose a reason for hiding this comment

octogonz May 2, 2020

Choose a reason for hiding this comment

Feiyang1 May 2, 2020

Choose a reason for hiding this comment

octogonz May 3, 2020 • edited Loading

Choose a reason for hiding this comment

Option 1: DocCodeSpan (original approach)

f() function

Parameters

Option 2: DocPlainText

f() function

Parameters

octogonz May 3, 2020 • edited Loading

Choose a reason for hiding this comment

Option 3: links inside <code>

f() function

Parameters

octogonz May 3, 2020

Choose a reason for hiding this comment

Feiyang1 May 4, 2020

Choose a reason for hiding this comment

octogonz commented May 6, 2020

octogonz commented May 6, 2020

octogonz commented May 6, 2020

Feiyang1 commented May 6, 2020

Feiyang1 commented Apr 29, 2020 •

edited

Loading

msftclas commented Apr 29, 2020 •

edited

Loading

octogonz May 3, 2020 •

edited

Loading

octogonz May 3, 2020 •

edited

Loading

Option 3: links inside `<code>`