[reactive-element] Expand jsdoc documentation, and misc code sample syntax fixes. #2457

AndrewJakubowicz · 2022-01-26T19:25:29Z

This PR was originally to make some minor fixes to the reactive-element code samples, but I expanded it slightly to also include documentation for willUpdate, firstUpdated, and the attributeChangedCallback.

The documentation updates are scoped to the reactive-element package.

Documentation added to `willUpdate` lifecycle callback. Code examples and doc additions to `firstUpdated` and `attributeChangedCallback`. Otherwise small fixes.

changeset-bot · 2022-01-26T19:25:31Z

🦋 Changeset detected

Latest commit: d9158f1

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 · 2022-01-26T19:25:59Z

📊 Tachometer Benchmark Results

Summary

nop-update

lit-html-kitchen-sink: unsure 🔍 -10% - +4% (-3.53ms - +1.39ms)
^{this-change vs tip-of-tree}

render

lit-element-list: unsure 🔍 -2% - +1% (-2.54ms - +1.00ms)
^{this-change vs tip-of-tree}
lit-html-kitchen-sink: unsure 🔍 -6% - +2% (-2.58ms - +0.73ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -7% - +4% (-1.00ms - +0.56ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -3% - +2% (-1.91ms - +1.73ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -1% - +2% (-1.15ms - +1.16ms)
^{this-change vs tip-of-tree}

update

lit-element-list: unsure 🔍 -1% - +1% (-14.53ms - +14.77ms)
^{this-change vs tip-of-tree}
lit-html-kitchen-sink: unsure 🔍 -3% - +6% (-2.99ms - +6.37ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -2% - +2% (-6.27ms - +6.05ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -4% - +1% (-7.17ms - +2.46ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -0% - +2% (-2.33ms - +23.40ms)
^{this-change vs tip-of-tree}

update-reflect

lit-element-list: unsure 🔍 -2% - +1% (-21.16ms - +6.52ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -1% - +2% (-11.54ms - +17.66ms)
^{this-change vs tip-of-tree}

Results

lit-element-list

Browser: chrome-headless 97.0.4692.99
Sample size: 50
Built by: Benchmarks #2300
Commit: fe1741e

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	104.98ms - 106.65ms	-	unsure 🔍 -2% - +1% -2.54ms - +1.00ms	faster ✔ 22% - 24% 29.72ms - 32.89ms
tip-of-tree tip-of-tree	105.02ms - 108.15ms	unsure 🔍 -1% - +2% -1.00ms - +2.54ms	-	faster ✔ 21% - 24% 28.47ms - 32.61ms
previous-release previous-release	135.77ms - 138.47ms	slower ❌ 28% - 31% 29.72ms - 32.89ms	slower ❌ 26% - 31% 28.47ms - 32.61ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	996.05ms - 1016.63ms	-	unsure 🔍 -1% - +1% -14.53ms - +14.77ms	faster ✔ 6% - 9% 70.29ms - 99.19ms
tip-of-tree tip-of-tree	995.79ms - 1016.66ms	unsure 🔍 -1% - +1% -14.77ms - +14.53ms	-	faster ✔ 6% - 9% 70.30ms - 99.41ms
previous-release previous-release	1080.93ms - 1101.23ms	slower ❌ 7% - 10% 70.29ms - 99.19ms	slower ❌ 7% - 10% 70.30ms - 99.41ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1101.38ms - 1118.77ms	-	unsure 🔍 -2% - +1% -21.16ms - +6.52ms	faster ✔ 5% - 7% 55.08ms - 83.97ms
tip-of-tree tip-of-tree	1106.63ms - 1128.17ms	unsure 🔍 -1% - +2% -6.52ms - +21.16ms	-	faster ✔ 4% - 7% 46.42ms - 77.99ms
previous-release previous-release	1168.07ms - 1191.14ms	slower ❌ 5% - 8% 55.08ms - 83.97ms	slower ❌ 4% - 7% 46.42ms - 77.99ms	-

lit-html-kitchen-sink

Browser: chrome-headless 97.0.4692.99
Sample size: 30
Built by: Benchmarks #2300
Commit: fe1741e

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	44.17ms - 45.64ms	-	unsure 🔍 -6% - +2% -2.58ms - +0.73ms	faster ✔ 10% - 15% 4.76ms - 7.83ms
tip-of-tree tip-of-tree	44.35ms - 47.31ms	unsure 🔍 -2% - +6% -0.73ms - +2.58ms	-	faster ✔ 7% - 14% 3.37ms - 7.37ms
previous-release previous-release	49.86ms - 52.54ms	slower ❌ 10% - 18% 4.76ms - 7.83ms	slower ❌ 7% - 16% 3.37ms - 7.37ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	114.15ms - 121.51ms	-	unsure 🔍 -3% - +6% -2.99ms - +6.37ms	unsure 🔍 -6% - +1% -7.19ms - +1.78ms
tip-of-tree tip-of-tree	113.25ms - 119.02ms	unsure 🔍 -5% - +3% -6.37ms - +2.99ms	-	faster ✔ 0% - 7% 0.53ms - 8.25ms
previous-release previous-release	117.97ms - 123.09ms	unsure 🔍 -2% - +6% -1.78ms - +7.19ms	slower ❌ 0% - 7% 0.53ms - 8.25ms	-

nop-update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	33.10ms - 35.03ms	-	unsure 🔍 -10% - +4% -3.53ms - +1.39ms	faster ✔ 8% - 15% 3.16ms - 5.82ms
tip-of-tree tip-of-tree	32.88ms - 37.40ms	unsure 🔍 -4% - +10% -1.39ms - +3.53ms	-	faster ✔ 3% - 15% 0.98ms - 5.85ms
previous-release previous-release	37.64ms - 39.46ms	slower ❌ 9% - 17% 3.16ms - 5.82ms	slower ❌ 2% - 17% 0.98ms - 5.85ms	-

lit-html-repeat

Browser: chrome-headless 97.0.4692.99
Sample size: 30
Built by: Benchmarks #2300
Commit: fe1741e

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	14.32ms - 15.23ms	-	unsure 🔍 -7% - +4% -1.00ms - +0.56ms	faster ✔ 7% - 13% 1.17ms - 2.23ms
tip-of-tree tip-of-tree	14.36ms - 15.63ms	unsure 🔍 -4% - +7% -0.56ms - +1.00ms	-	faster ✔ 5% - 13% 0.79ms - 2.17ms
previous-release previous-release	16.21ms - 16.74ms	slower ❌ 8% - 15% 1.17ms - 2.23ms	slower ❌ 5% - 15% 0.79ms - 2.17ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	365.98ms - 374.80ms	-	unsure 🔍 -2% - +2% -6.27ms - +6.05ms	faster ✔ 31% - 33% 168.41ms - 180.60ms
tip-of-tree tip-of-tree	366.20ms - 374.80ms	unsure 🔍 -2% - +2% -6.05ms - +6.27ms	-	faster ✔ 31% - 33% 168.39ms - 180.41ms
previous-release previous-release	540.70ms - 549.10ms	slower ❌ 45% - 49% 168.41ms - 180.60ms	slower ❌ 45% - 49% 168.39ms - 180.41ms	-

lit-html-template-heavy

Browser: chrome-headless 97.0.4692.99
Sample size: 50
Built by: Benchmarks #2300
Commit: fe1741e

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	72.81ms - 75.35ms	-	unsure 🔍 -3% - +2% -1.91ms - +1.73ms	faster ✔ 14% - 17% 11.81ms - 15.41ms
tip-of-tree tip-of-tree	72.87ms - 75.47ms	unsure 🔍 -2% - +3% -1.73ms - +1.91ms	-	faster ✔ 13% - 17% 11.70ms - 15.34ms
previous-release previous-release	86.41ms - 88.96ms	slower ❌ 16% - 21% 11.81ms - 15.41ms	slower ❌ 16% - 21% 11.70ms - 15.34ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	165.14ms - 171.21ms	-	unsure 🔍 -4% - +1% -7.17ms - +2.46ms	faster ✔ 13% - 17% 24.93ms - 33.77ms
tip-of-tree tip-of-tree	166.79ms - 174.27ms	unsure 🔍 -1% - +4% -2.46ms - +7.17ms	-	faster ✔ 11% - 16% 22.06ms - 31.93ms
previous-release previous-release	194.31ms - 200.74ms	slower ❌ 15% - 20% 24.93ms - 33.77ms	slower ❌ 13% - 19% 22.06ms - 31.93ms	-

reactive-element-list

Browser: chrome-headless 97.0.4692.99
Sample size: 50
Built by: Benchmarks #2300
Commit: fe1741e

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	75.91ms - 77.28ms	-	unsure 🔍 -1% - +2% -1.15ms - +1.16ms	unsure 🔍 -1% - +2% -0.65ms - +1.36ms
tip-of-tree tip-of-tree	75.66ms - 77.52ms	unsure 🔍 -2% - +1% -1.16ms - +1.15ms	-	unsure 🔍 -1% - +2% -0.83ms - +1.54ms
previous-release previous-release	75.50ms - 76.98ms	unsure 🔍 -2% - +1% -1.36ms - +0.65ms	unsure 🔍 -2% - +1% -1.54ms - +0.83ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1022.21ms - 1042.66ms	-	unsure 🔍 -0% - +2% -2.33ms - +23.40ms	unsure 🔍 -1% - +2% -12.97ms - +17.25ms
tip-of-tree tip-of-tree	1014.10ms - 1029.70ms	unsure 🔍 -2% - +0% -23.40ms - +2.33ms	-	unsure 🔍 -2% - +0% -21.98ms - +5.19ms
previous-release previous-release	1019.17ms - 1041.42ms	unsure 🔍 -2% - +1% -17.25ms - +12.97ms	unsure 🔍 -1% - +2% -5.19ms - +21.98ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1132.92ms - 1153.75ms	-	unsure 🔍 -1% - +2% -11.54ms - +17.66ms	unsure 🔍 -2% - +1% -19.42ms - +13.48ms
tip-of-tree tip-of-tree	1130.05ms - 1150.51ms	unsure 🔍 -2% - +1% -17.66ms - +11.54ms	-	unsure 🔍 -2% - +1% -22.36ms - +10.30ms
previous-release previous-release	1133.58ms - 1159.03ms	unsure 🔍 -1% - +2% -13.48ms - +19.42ms	unsure 🔍 -1% - +2% -10.30ms - +22.36ms	-

_{tachometer-reporter-action v2 for Benchmarks}

augustjk

Nice! Helpful comments and examples!

arthurevans

LGTM. Some minor very optional suggestions. Please dismiss them if you don't feel they make sense in the context where this doc will appear.

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

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

Co-authored-by: Arthur Evans <arthure@google.com>

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

packages/reactive-element/src/reactive-element.ts

AndrewJakubowicz added 2 commits January 26, 2022 11:04

[reactive-element] JSDoc fixes and improvements.

5ad613c

Documentation added to `willUpdate` lifecycle callback. Code examples and doc additions to `firstUpdated` and `attributeChangedCallback`. Otherwise small fixes.

Add changeset

677aafd

AndrewJakubowicz requested a review from justinfagnani as a code owner January 26, 2022 19:25

AndrewJakubowicz mentioned this pull request Jan 26, 2022

[all] Expand jsdoc documentation #1883

Open

AndrewJakubowicz requested a review from augustjk January 26, 2022 19:32

augustjk approved these changes Jan 26, 2022

View reviewed changes

AndrewJakubowicz requested review from arthurevans and removed request for justinfagnani January 26, 2022 20:01

arthurevans approved these changes Jan 28, 2022

View reviewed changes

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

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

AndrewJakubowicz and others added 2 commits January 28, 2022 14:24

Update packages/reactive-element/src/decorators/query-assigned-nodes.ts

7f9c450

Co-authored-by: Arthur Evans <arthure@google.com>

Doc review feedback

37911fc

justinfagnani reviewed Jan 28, 2022

View reviewed changes

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

packages/reactive-element/src/reactive-element.ts Outdated Show resolved Hide resolved

Add Justin's feedback. Expanded attributeChangedCallback JSDocs.

d9158f1

justinfagnani approved these changes Jan 29, 2022

View reviewed changes

AndrewJakubowicz merged commit 48d6918 into main Jan 31, 2022

AndrewJakubowicz deleted the docs-reactive-element branch January 31, 2022 16:49

lit-robot mentioned this pull request Feb 7, 2022

Version Packages #2500

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[reactive-element] Expand jsdoc documentation, and misc code sample syntax fixes. #2457

[reactive-element] Expand jsdoc documentation, and misc code sample syntax fixes. #2457

AndrewJakubowicz commented Jan 26, 2022

changeset-bot bot commented Jan 26, 2022 •

edited

github-actions bot commented Jan 26, 2022 •

edited

📊 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

augustjk left a comment

arthurevans left a comment

[reactive-element] Expand jsdoc documentation, and misc code sample syntax fixes. #2457

[reactive-element] Expand jsdoc documentation, and misc code sample syntax fixes. #2457

Conversation

AndrewJakubowicz commented Jan 26, 2022

changeset-bot bot commented Jan 26, 2022 • edited

🦋 Changeset detected

github-actions bot commented Jan 26, 2022 • edited

📊 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

augustjk left a comment

Choose a reason for hiding this comment

arthurevans left a comment

Choose a reason for hiding this comment

changeset-bot bot commented Jan 26, 2022 •

edited

github-actions bot commented Jan 26, 2022 •

edited