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

[AndrewJakubowicz]

Raised in lit/lit.dev#623

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]

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

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

[AndrewJakubowicz]

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!