Improve docs to more clearly link to the options interface for queryAssignedNodes #2360

AndrewJakubowicz · 2021-12-14T19:15:32Z

This change makes the link to the options object clearer for both queryAssignedElements and queryAssignedNodes.

Initially wanted to link from the @param options jsdoc, but it's not yet supported on Lit.dev.

It's easier to document this currently with the TypeScript types and a link in the description documentation. Once lit/lit.dev#503 is addressed we can update this with @link and @param providing the best of both worlds.

Tested manually with lit.dev api generation.

This now shows up like so and the link can be clicked. Information is de-duped:

changeset-bot · 2021-12-14T19:15:35Z

🦋 Changeset detected

Latest commit: 825239a

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-14T19:16:02Z

📊 Tachometer Benchmark Results

Summary

nop-update

lit-html-kitchen-sink: unsure 🔍 -6% - +8% (-2.05ms - +2.74ms)
^{this-change vs tip-of-tree}

render

lit-element-list: unsure 🔍 -4% - +2% (-4.19ms - +2.73ms)
^{this-change vs tip-of-tree}
lit-html-kitchen-sink: unsure 🔍 -4% - +5% (-2.01ms - +2.53ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -4% - +6% (-0.57ms - +0.90ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -2% - +6% (-1.08ms - +4.08ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -5% - +2% (-3.82ms - +1.23ms)
^{this-change vs tip-of-tree}

update

lit-element-list: unsure 🔍 -3% - +2% (-25.48ms - +23.11ms)
^{this-change vs tip-of-tree}
lit-html-kitchen-sink: unsure 🔍 -6% - +5% (-7.04ms - +6.08ms)
^{this-change vs tip-of-tree}
lit-html-repeat: slower ❌ 0% - 3% (1.32ms - 11.40ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -4% - +2% (-7.10ms - +3.09ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -2% - +2% (-15.37ms - +15.27ms)
^{this-change vs tip-of-tree}

update-reflect

lit-element-list: unsure 🔍 -4% - +1% (-42.61ms - +11.25ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -2% - +1% (-21.07ms - +8.60ms)
^{this-change vs tip-of-tree}

Results

lit-element-list

Browser: chrome-headless 96.0.4664.93
Sample size: 50
Built by: Benchmarks #2158
Commit: 1f3af4e

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	109.14ms - 113.43ms	-	unsure 🔍 -4% - +2% -4.19ms - +2.73ms	faster ✔ 19% - 25% 26.65ms - 36.13ms
tip-of-tree tip-of-tree	109.30ms - 114.72ms	unsure 🔍 -2% - +4% -2.73ms - +4.19ms	-	faster ✔ 18% - 24% 25.63ms - 35.68ms
previous-release previous-release	138.44ms - 146.90ms	slower ❌ 24% - 33% 26.65ms - 36.13ms	slower ❌ 22% - 32% 25.63ms - 35.68ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	995.27ms - 1031.24ms	-	unsure 🔍 -3% - +2% -25.48ms - +23.11ms	faster ✔ 6% - 10% 59.96ms - 110.23ms
tip-of-tree tip-of-tree	998.11ms - 1030.77ms	unsure 🔍 -2% - +3% -23.11ms - +25.48ms	-	faster ✔ 6% - 10% 59.94ms - 107.89ms
previous-release previous-release	1080.80ms - 1115.91ms	slower ❌ 6% - 11% 59.96ms - 110.23ms	slower ❌ 6% - 11% 59.94ms - 107.89ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1097.13ms - 1131.42ms	-	unsure 🔍 -4% - +1% -42.61ms - +11.25ms	faster ✔ 3% - 7% 35.30ms - 87.07ms
tip-of-tree tip-of-tree	1109.18ms - 1150.72ms	unsure 🔍 -1% - +4% -11.25ms - +42.61ms	-	faster ✔ 1% - 6% 17.09ms - 73.92ms
previous-release previous-release	1156.06ms - 1194.85ms	slower ❌ 3% - 8% 35.30ms - 87.07ms	slower ❌ 1% - 7% 17.09ms - 73.92ms	-

lit-html-kitchen-sink

Browser: chrome-headless 96.0.4664.93
Sample size: 30
Built by: Benchmarks #2158
Commit: 1f3af4e

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	45.53ms - 48.68ms	-	unsure 🔍 -4% - +5% -2.01ms - +2.53ms	faster ✔ 8% - 17% 4.23ms - 9.33ms
tip-of-tree tip-of-tree	45.21ms - 48.48ms	unsure 🔍 -5% - +4% -2.53ms - +2.01ms	-	faster ✔ 9% - 18% 4.46ms - 9.63ms
previous-release previous-release	51.88ms - 55.89ms	slower ❌ 9% - 20% 4.23ms - 9.33ms	slower ❌ 9% - 21% 4.46ms - 9.63ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	114.85ms - 125.33ms	-	unsure 🔍 -6% - +5% -7.04ms - +6.08ms	unsure 🔍 -5% - +7% -6.15ms - +7.94ms
tip-of-tree tip-of-tree	116.62ms - 124.51ms	unsure 🔍 -5% - +6% -6.08ms - +7.04ms	-	unsure 🔍 -4% - +6% -4.77ms - +7.51ms
previous-release previous-release	114.49ms - 123.90ms	unsure 🔍 -7% - +5% -7.94ms - +6.15ms	unsure 🔍 -6% - +4% -7.51ms - +4.77ms	-

nop-update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	34.33ms - 38.34ms	-	unsure 🔍 -6% - +8% -2.05ms - +2.74ms	faster ✔ 3% - 16% 0.95ms - 6.63ms
tip-of-tree tip-of-tree	34.68ms - 37.30ms	unsure 🔍 -7% - +6% -2.74ms - +2.05ms	-	faster ✔ 5% - 16% 1.73ms - 6.53ms
previous-release previous-release	38.11ms - 42.14ms	slower ❌ 2% - 19% 0.95ms - 6.63ms	slower ❌ 5% - 18% 1.73ms - 6.53ms	-

lit-html-repeat

Browser: chrome-headless 96.0.4664.93
Sample size: 30
Built by: Benchmarks #2158
Commit: 1f3af4e

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	14.19ms - 15.44ms	-	unsure 🔍 -4% - +6% -0.57ms - +0.90ms	faster ✔ 4% - 14% 0.61ms - 2.37ms
tip-of-tree tip-of-tree	14.27ms - 15.03ms	unsure 🔍 -6% - +4% -0.90ms - +0.57ms	-	faster ✔ 6% - 14% 0.93ms - 2.39ms
previous-release previous-release	15.69ms - 16.93ms	slower ❌ 4% - 16% 0.61ms - 2.37ms	slower ❌ 6% - 16% 0.93ms - 2.39ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	366.81ms - 373.71ms	-	slower ❌ 0% - 3% 1.32ms - 11.40ms	faster ✔ 31% - 33% 164.82ms - 183.28ms
tip-of-tree tip-of-tree	360.23ms - 367.57ms	faster ✔ 0% - 3% 1.32ms - 11.40ms	-	faster ✔ 32% - 34% 171.10ms - 189.73ms
previous-release previous-release	535.75ms - 552.87ms	slower ❌ 44% - 50% 164.82ms - 183.28ms	slower ❌ 47% - 52% 171.10ms - 189.73ms	-

lit-html-template-heavy

Browser: chrome-headless 96.0.4664.93
Sample size: 50
Built by: Benchmarks #2158
Commit: 1f3af4e

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	71.47ms - 75.61ms	-	unsure 🔍 -2% - +6% -1.08ms - +4.08ms	faster ✔ 12% - 18% 10.16ms - 15.37ms
tip-of-tree tip-of-tree	70.51ms - 73.58ms	unsure 🔍 -5% - +1% -4.08ms - +1.08ms	-	faster ✔ 14% - 19% 12.06ms - 16.47ms
previous-release previous-release	84.73ms - 87.89ms	slower ❌ 13% - 21% 10.16ms - 15.37ms	slower ❌ 16% - 23% 12.06ms - 16.47ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	153.59ms - 158.85ms	-	unsure 🔍 -4% - +2% -7.10ms - +3.09ms	faster ✔ 12% - 16% 20.64ms - 28.57ms
tip-of-tree tip-of-tree	153.86ms - 162.60ms	unsure 🔍 -2% - +5% -3.09ms - +7.10ms	-	faster ✔ 10% - 15% 17.31ms - 27.88ms
previous-release previous-release	177.86ms - 183.80ms	slower ❌ 13% - 18% 20.64ms - 28.57ms	slower ❌ 11% - 18% 17.31ms - 27.88ms	-

reactive-element-list

Browser: chrome-headless 96.0.4664.93
Sample size: 50
Built by: Benchmarks #2158
Commit: 1f3af4e

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	76.21ms - 79.10ms	-	unsure 🔍 -5% - +2% -3.82ms - +1.23ms	unsure 🔍 -3% - +3% -2.15ms - +2.57ms
tip-of-tree tip-of-tree	76.88ms - 81.02ms	unsure 🔍 -2% - +5% -1.23ms - +3.82ms	-	unsure 🔍 -2% - +6% -1.28ms - +4.29ms
previous-release previous-release	75.58ms - 79.31ms	unsure 🔍 -3% - +3% -2.57ms - +2.15ms	unsure 🔍 -5% - +2% -4.29ms - +1.28ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1002.67ms - 1023.83ms	-	unsure 🔍 -2% - +2% -15.37ms - +15.27ms	unsure 🔍 -1% - +1% -15.15ms - +15.18ms
tip-of-tree tip-of-tree	1002.22ms - 1024.38ms	unsure 🔍 -2% - +2% -15.27ms - +15.37ms	-	unsure 🔍 -2% - +2% -15.45ms - +15.59ms
previous-release previous-release	1002.37ms - 1024.10ms	unsure 🔍 -1% - +1% -15.18ms - +15.15ms	unsure 🔍 -2% - +2% -15.59ms - +15.45ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1117.47ms - 1135.41ms	-	unsure 🔍 -2% - +1% -21.07ms - +8.60ms	unsure 🔍 -1% - +1% -10.34ms - +14.07ms
tip-of-tree tip-of-tree	1120.86ms - 1144.49ms	unsure 🔍 -1% - +2% -8.60ms - +21.07ms	-	unsure 🔍 -1% - +2% -6.32ms - +22.52ms
previous-release previous-release	1116.30ms - 1132.85ms	unsure 🔍 -1% - +1% -14.07ms - +10.34ms	unsure 🔍 -2% - +1% -22.52ms - +6.32ms	-

_{tachometer-reporter-action v2 for Benchmarks}

aomarks

Nice!

…ryAssignedNodes. Raised in lit/lit.dev#623

packages/reactive-element/src/decorators/query-assigned-elements.ts

See lit/lit.dev#503 for @link issue.

AndrewJakubowicz · 2021-12-14T22:35:15Z

I de-duped the information, and also made sure that it generates correctly on Lit.dev. In the generated docs there is now a link to the interface which contains more context. Thank you!

aomarks

Great!

AndrewJakubowicz requested a review from justinfagnani as a code owner December 14, 2021 19:15

aomarks approved these changes Dec 14, 2021

View reviewed changes

Improve generated docs to more clearly link to options object for que…

1b67e03

…ryAssignedNodes. Raised in lit/lit.dev#623

AndrewJakubowicz force-pushed the query-assigned-nodes-docs branch from e84a576 to 1b67e03 Compare December 14, 2021 19:32

justinfagnani reviewed Dec 14, 2021

View reviewed changes

packages/reactive-element/src/decorators/query-assigned-elements.ts Outdated Show resolved Hide resolved

Remove duplication of options object. Address Justin's feedback.

dce5aba

AndrewJakubowicz force-pushed the query-assigned-nodes-docs branch 2 times, most recently from 9d83806 to ff0faa9 Compare December 14, 2021 22:16

Revert to a link syntax lit.dev understands.

6283acd

See lit/lit.dev#503 for @link issue.

AndrewJakubowicz force-pushed the query-assigned-nodes-docs branch from ff0faa9 to 6283acd Compare December 14, 2021 22:19

AndrewJakubowicz requested review from aomarks and justinfagnani December 14, 2021 22:36

Include changeset for change.

825239a

justinfagnani approved these changes Dec 14, 2021

View reviewed changes

aomarks approved these changes Dec 14, 2021

View reviewed changes

AndrewJakubowicz merged commit 08e7fc5 into main Dec 14, 2021

AndrewJakubowicz deleted the query-assigned-nodes-docs branch December 14, 2021 23:25

This was referenced Jan 5, 2022

Version Packages #2375

Closed

Version Packages #2377

Merged

Improve docs to more clearly link to the options interface for queryAssignedNodes #2360

Improve docs to more clearly link to the options interface for queryAssignedNodes #2360

Uh oh!

Conversation

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

Uh oh!

Uh oh!

changeset-bot bot commented Dec 14, 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 14, 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 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

aomarks left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AndrewJakubowicz commented Dec 14, 2021 •

edited

Loading

changeset-bot bot commented Dec 14, 2021 •

edited

Loading

github-actions bot commented Dec 14, 2021 •

edited

Loading

AndrewJakubowicz commented Dec 14, 2021 •

edited

Loading