Replace jsdoc symbol links with @linkcode instead of square brackets #2370

AndrewJakubowicz · 2021-12-21T22:16:47Z

Context

Currently we support [[symbol]] in our documentation to create an automated hyperlink in our generated lit.dev API documentation. However [[symbol]] isn't recognized by VS code and ends up being rendered directly into the documentation.

Instead if we use {@link symbol} or {@linkcode symbol} then we get automatic hyperlinks and jump to definition in the IDE hover documentation if the linked symbol is in scope. If the symbol is not in scope the IDE experience is similar to currently where the link text is directly printed into the documentation.

This change should follow lit.dev's change lit/lit.dev#629 which adds logic to handle transforming @link and @linkcode.

Testing

This was tested manually by hovering over the symbols, and using this PR to generate Lit.dev documentation.

Open questions

Some of the links reference symbols that aren't imported or in scope. Is it worth importing the symbols as type only for the purpose of documentation?

Screenshots

In editor, hover documentation on main branch:

In editor, hover documentation with this change:

Generated documentation on lit.dev (for both):

changeset-bot · 2021-12-21T22:16:49Z

🦋 Changeset detected

Latest commit: d0cbb19

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2021-12-21T22:17:11Z

📊 Tachometer Benchmark Results

Summary

nop-update

lit-html-kitchen-sink: unsure 🔍 -10% - +8% (-3.14ms - +2.66ms)
^{this-change vs tip-of-tree}

render

lit-element-list: unsure 🔍 -2% - +1% (-1.52ms - +1.29ms)
^{this-change vs tip-of-tree}
lit-html-kitchen-sink: unsure 🔍 -3% - +5% (-0.94ms - +1.90ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -3% - +4% (-0.33ms - +0.57ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -3% - +1% (-1.74ms - +0.74ms)
^{this-change vs tip-of-tree}
reactive-element-list: faster ✔ 0% - 4% (0.10ms - 2.56ms)
^{this-change vs tip-of-tree}

update

lit-element-list: unsure 🔍 -0% - +2% (-1.47ms - +18.22ms)
^{this-change vs tip-of-tree}
lit-html-kitchen-sink: unsure 🔍 -7% - +6% (-7.38ms - +5.90ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -1% - +2% (-3.68ms - +5.45ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -3% - +1% (-4.10ms - +1.06ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -2% - +1% (-13.98ms - +8.52ms)
^{this-change vs tip-of-tree}

update-reflect

lit-element-list: unsure 🔍 -1% - +2% (-7.37ms - +16.51ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -2% - +1% (-15.69ms - +9.58ms)
^{this-change vs tip-of-tree}

Results

lit-element-list

Browser: chrome-headless 97.0.4692.71
Sample size: 50
Built by: Benchmarks #2247
Commit: d0c59b0

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	86.62ms - 88.48ms	-	unsure 🔍 -2% - +1% -1.52ms - +1.29ms	faster ✔ 21% - 23% 23.13ms - 26.27ms
tip-of-tree tip-of-tree	86.62ms - 88.72ms	unsure 🔍 -1% - +2% -1.29ms - +1.52ms	-	faster ✔ 21% - 23% 22.94ms - 26.23ms
previous-release previous-release	110.99ms - 113.52ms	slower ❌ 26% - 30% 23.13ms - 26.27ms	slower ❌ 26% - 30% 22.94ms - 26.23ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	870.51ms - 883.36ms	-	unsure 🔍 -0% - +2% -1.47ms - +18.22ms	faster ✔ 7% - 9% 61.73ms - 85.38ms
tip-of-tree tip-of-tree	861.10ms - 876.02ms	unsure 🔍 -2% - +0% -18.22ms - +1.47ms	-	faster ✔ 7% - 10% 69.52ms - 94.35ms
previous-release previous-release	940.57ms - 960.41ms	slower ❌ 7% - 10% 61.73ms - 85.38ms	slower ❌ 8% - 11% 69.52ms - 94.35ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	974.12ms - 991.68ms	-	unsure 🔍 -1% - +2% -7.37ms - +16.51ms	faster ✔ 3% - 5% 25.55ms - 49.84ms
tip-of-tree tip-of-tree	970.24ms - 986.42ms	unsure 🔍 -2% - +1% -16.51ms - +7.37ms	-	faster ✔ 3% - 5% 30.60ms - 53.92ms
previous-release previous-release	1012.20ms - 1028.98ms	slower ❌ 3% - 5% 25.55ms - 49.84ms	slower ❌ 3% - 6% 30.60ms - 53.92ms	-

lit-html-kitchen-sink

Browser: chrome-headless 97.0.4692.71
Sample size: 30
Built by: Benchmarks #2247
Commit: d0c59b0

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	35.21ms - 37.47ms	-	unsure 🔍 -3% - +5% -0.94ms - +1.90ms	faster ✔ 13% - 23% 5.17ms - 10.47ms
tip-of-tree tip-of-tree	35.00ms - 36.73ms	unsure 🔍 -5% - +3% -1.90ms - +0.94ms	-	faster ✔ 14% - 24% 5.75ms - 10.84ms
previous-release previous-release	41.76ms - 46.56ms	slower ❌ 14% - 29% 5.17ms - 10.47ms	slower ❌ 16% - 30% 5.75ms - 10.84ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	94.36ms - 104.99ms	-	unsure 🔍 -7% - +6% -7.38ms - +5.90ms	unsure 🔍 -9% - +4% -9.70ms - +3.91ms
tip-of-tree tip-of-tree	96.44ms - 104.39ms	unsure 🔍 -6% - +7% -5.90ms - +7.38ms	-	unsure 🔍 -8% - +4% -7.98ms - +3.66ms
previous-release previous-release	98.32ms - 106.82ms	unsure 🔍 -4% - +10% -3.91ms - +9.70ms	unsure 🔍 -4% - +8% -3.66ms - +7.98ms	-

nop-update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	29.38ms - 33.71ms	-	unsure 🔍 -10% - +8% -3.14ms - +2.66ms	faster ✔ 5% - 19% 1.60ms - 6.99ms
tip-of-tree tip-of-tree	29.85ms - 33.72ms	unsure 🔍 -8% - +10% -2.66ms - +3.14ms	-	faster ✔ 5% - 18% 1.54ms - 6.57ms
previous-release previous-release	34.23ms - 37.45ms	slower ❌ 4% - 23% 1.60ms - 6.99ms	slower ❌ 4% - 21% 1.54ms - 6.57ms	-

lit-html-repeat

Browser: chrome-headless 97.0.4692.71
Sample size: 30
Built by: Benchmarks #2247
Commit: d0c59b0

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	12.75ms - 13.27ms	-	unsure 🔍 -3% - +4% -0.33ms - +0.57ms	faster ✔ 8% - 12% 1.11ms - 1.73ms
tip-of-tree tip-of-tree	12.53ms - 13.26ms	unsure 🔍 -4% - +3% -0.57ms - +0.33ms	-	faster ✔ 8% - 13% 1.13ms - 1.94ms
previous-release previous-release	14.26ms - 14.60ms	slower ❌ 8% - 13% 1.11ms - 1.73ms	slower ❌ 8% - 15% 1.13ms - 1.94ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	354.42ms - 361.78ms	-	unsure 🔍 -1% - +2% -3.68ms - +5.45ms	faster ✔ 30% - 32% 154.00ms - 167.51ms
tip-of-tree tip-of-tree	354.53ms - 359.91ms	unsure 🔍 -2% - +1% -5.45ms - +3.68ms	-	faster ✔ 30% - 32% 155.36ms - 167.91ms
previous-release previous-release	513.19ms - 524.52ms	slower ❌ 43% - 47% 154.00ms - 167.51ms	slower ❌ 43% - 47% 155.36ms - 167.91ms	-

lit-html-template-heavy

Browser: chrome-headless 97.0.4692.71
Sample size: 50
Built by: Benchmarks #2247
Commit: d0c59b0

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	62.56ms - 64.25ms	-	unsure 🔍 -3% - +1% -1.74ms - +0.74ms	faster ✔ 16% - 19% 11.82ms - 14.99ms
tip-of-tree tip-of-tree	63.00ms - 64.82ms	unsure 🔍 -1% - +3% -0.74ms - +1.74ms	-	faster ✔ 15% - 19% 11.28ms - 14.53ms
previous-release previous-release	75.46ms - 78.16ms	slower ❌ 18% - 24% 11.82ms - 14.99ms	slower ❌ 17% - 23% 11.28ms - 14.53ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	138.92ms - 141.89ms	-	unsure 🔍 -3% - +1% -4.10ms - +1.06ms	faster ✔ 12% - 15% 19.85ms - 24.90ms
tip-of-tree tip-of-tree	139.81ms - 144.03ms	unsure 🔍 -1% - +3% -1.06ms - +4.10ms	-	faster ✔ 11% - 15% 17.92ms - 23.80ms
previous-release previous-release	160.74ms - 164.82ms	slower ❌ 14% - 18% 19.85ms - 24.90ms	slower ❌ 12% - 17% 17.92ms - 23.80ms	-

reactive-element-list

Browser: chrome-headless 97.0.4692.71
Sample size: 50
Built by: Benchmarks #2247
Commit: d0c59b0

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	62.69ms - 64.25ms	-	faster ✔ 0% - 4% 0.10ms - 2.56ms	faster ✔ 0% - 4% 0.29ms - 2.73ms
tip-of-tree tip-of-tree	63.85ms - 65.75ms	slower ❌ 0% - 4% 0.10ms - 2.56ms	-	unsure 🔍 -2% - +2% -1.52ms - +1.16ms
previous-release previous-release	64.04ms - 65.92ms	slower ❌ 0% - 4% 0.29ms - 2.73ms	unsure 🔍 -2% - +2% -1.16ms - +1.52ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	893.77ms - 909.88ms	-	unsure 🔍 -2% - +1% -13.98ms - +8.52ms	unsure 🔍 -2% - +1% -13.76ms - +7.78ms
tip-of-tree tip-of-tree	896.70ms - 912.41ms	unsure 🔍 -1% - +2% -8.52ms - +13.98ms	-	unsure 🔍 -1% - +1% -10.87ms - +10.36ms
previous-release previous-release	897.67ms - 911.96ms	unsure 🔍 -1% - +2% -7.78ms - +13.76ms	unsure 🔍 -1% - +1% -10.36ms - +10.87ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1017.88ms - 1036.48ms	-	unsure 🔍 -2% - +1% -15.69ms - +9.58ms	unsure 🔍 -1% - +1% -13.52ms - +12.02ms
tip-of-tree tip-of-tree	1021.69ms - 1038.78ms	unsure 🔍 -1% - +2% -9.58ms - +15.69ms	-	unsure 🔍 -1% - +1% -9.92ms - +14.54ms
previous-release previous-release	1019.18ms - 1036.68ms	unsure 🔍 -1% - +1% -12.02ms - +13.52ms	unsure 🔍 -1% - +1% -14.54ms - +9.92ms	-

_{tachometer-reporter-action v2 for Benchmarks}

aomarks · 2022-01-20T22:41:22Z

Some of the links reference symbols that aren't imported or in scope. Is it worth importing the symbols as type only for the purpose of documentation?

Hmmm... maybe? What are some examples?

aomarks · 2022-01-20T22:41:38Z

Just needs a changeset

aomarks

Nice!

AndrewJakubowicz · 2022-01-20T23:22:17Z

Hmmm... maybe? What are some examples?

In the screenshot for LitElement, note that property isn't linked in the VS Code screenshot. One way this can be "fixed" is by adding a type only import: import type {property} from '@lit/reactive-element/decorators.js'; so the identifier is in scope.

I haven't investigated what other consequences an import like this might have. Previously these links didn't work in the editor so I think this change is still a valid incremental improvement.

…pport.

AndrewJakubowicz force-pushed the support-link-linkcode branch from 4c8ade5 to 90fed6a Compare December 21, 2021 22:39

AndrewJakubowicz mentioned this pull request Dec 21, 2021

Add @link and @linkcode support in generated API docs lit/lit.dev#629

Merged

AndrewJakubowicz force-pushed the support-link-linkcode branch from 90fed6a to fd1762d Compare January 20, 2022 21:14

AndrewJakubowicz marked this pull request as ready for review January 20, 2022 22:32

AndrewJakubowicz requested a review from justinfagnani as a code owner January 20, 2022 22:32

AndrewJakubowicz requested a review from aomarks January 20, 2022 22:32

aomarks approved these changes Jan 20, 2022

View reviewed changes

AndrewJakubowicz changed the title ~~Replace doc links with @linkcode which has better IDE support~~ Replace jsdoc symbol links with @linkcode instead of square brackets Jan 20, 2022

AndrewJakubowicz added 2 commits January 21, 2022 19:09

Replace [[symbol]] doc links with @linkcode which has better IDE su…

6486012

…pport.

Add changelog

d0cbb19

AndrewJakubowicz force-pushed the support-link-linkcode branch from 71d2b2c to d0cbb19 Compare January 22, 2022 03:09

justinfagnani approved these changes Jan 23, 2022

View reviewed changes

AndrewJakubowicz merged commit 7453e36 into main Jan 24, 2022

AndrewJakubowicz deleted the support-link-linkcode branch January 24, 2022 17:05

github-actions bot mentioned this pull request Jan 25, 2022

Version Packages #2448

Merged

Replace jsdoc symbol links with @linkcode instead of square brackets #2370

Replace jsdoc symbol links with @linkcode instead of square brackets #2370

Uh oh!

Conversation

AndrewJakubowicz commented Dec 21, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context

Testing

Open questions

Screenshots

In editor, hover documentation on main branch:

In editor, hover documentation with this change:

Generated documentation on lit.dev (for both):

Uh oh!

changeset-bot bot commented Dec 21, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Dec 21, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Tachometer Benchmark Results

Summary

nop-update

render

update

update-reflect

Results

render

update

update-reflect

render

update

nop-update

render

update

render

update

render

update

update-reflect

Uh oh!

aomarks commented Jan 20, 2022

Uh oh!

aomarks commented Jan 20, 2022

Uh oh!

aomarks left a comment

Choose a reason for hiding this comment

Uh oh!

AndrewJakubowicz commented Jan 20, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AndrewJakubowicz commented Dec 21, 2021 •

edited

Loading

changeset-bot bot commented Dec 21, 2021 •

edited

Loading

github-actions bot commented Dec 21, 2021 •

edited

Loading

AndrewJakubowicz commented Jan 20, 2022 •

edited

Loading