Expand jsdoc documentation for reactive-element and lit-element.

[AndrewJakubowicz]

Context

Add some documentation for some public undocumented methods in lit-element and reactive-element. Addresses github issue: #1883

How

Used lit.dev documentation to guide the jsdocs, and addressed some class members that had no documentation on the lit.dev/docs/api pages.

Added some documentation for previously undocumented:

• LitElement.connectedCallback()
• LitElement.disconnectedCallback()
• ReactiveElement.hasUpdated
• ReactiveElement.addController
• ReactiveElement.removeController

Testing

Tested with mouse over in VsCode.

Thank you!

[changeset-bot]

🦋 Changeset detected

Latest commit: b036fd2

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 🔍 -1% - +0% (-0.38ms - +0.11ms)
  ^{this-change vs tip-of-tree}

render

• lit-element-list: unsure 🔍 -1% - +0% (-0.61ms - +0.35ms)
  ^{this-change vs tip-of-tree}
• lit-html-kitchen-sink: unsure 🔍 -1% - +2% (-0.34ms - +0.70ms)
  ^{this-change vs tip-of-tree}
• lit-html-repeat: unsure 🔍 -1% - +2% (-0.14ms - +0.24ms)
  ^{this-change vs tip-of-tree}
• lit-html-template-heavy: unsure 🔍 -1% - +0% (-0.83ms - +0.29ms)
  ^{this-change vs tip-of-tree}
• reactive-element-list: unsure 🔍 -1% - +1% (-0.47ms - +0.69ms)
  ^{this-change vs tip-of-tree}

update

• lit-element-list: unsure 🔍 -1% - +1% (-5.88ms - +7.65ms)
  ^{this-change vs tip-of-tree}
• lit-html-kitchen-sink: unsure 🔍 -1% - +2% (-1.23ms - +2.14ms)
  ^{this-change vs tip-of-tree}
• lit-html-repeat: unsure 🔍 -1% - +1% (-3.21ms - +3.27ms)
  ^{this-change vs tip-of-tree}
• lit-html-template-heavy: unsure 🔍 -2% - +1% (-1.96ms - +1.11ms)
  ^{this-change vs tip-of-tree}
• reactive-element-list: unsure 🔍 -1% - +0% (-9.28ms - +2.50ms)
  ^{this-change vs tip-of-tree}

update-reflect

• lit-element-list: unsure 🔍 -1% - +2% (-5.20ms - +11.45ms)
  ^{this-change vs tip-of-tree}
• reactive-element-list: unsure 🔍 -1% - +1% (-7.71ms - +4.59ms)
  ^{this-change vs tip-of-tree}

Results

lit-element-list

• Browser: chrome-headless 93.0.4577.63
• Sample size: 50
• Built by: Benchmarks #1946

• Commit: 6ab760a

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	84.81ms - 85.46ms	-	unsure 🔍 -1% - +0% -0.61ms - +0.35ms	faster ✔ 19% - 20% 19.78ms - 20.66ms
tip-of-tree tip-of-tree	84.91ms - 85.62ms	unsure 🔍 -0% - +1% -0.35ms - +0.61ms	-	faster ✔ 19% - 19% 19.63ms - 20.55ms
previous-release previous-release	105.06ms - 105.65ms	slower ❌ 23% - 24% 19.78ms - 20.66ms	slower ❌ 23% - 24% 19.63ms - 20.55ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	699.34ms - 708.45ms	-	unsure 🔍 -1% - +1% -5.88ms - +7.65ms	faster ✔ 8% - 10% 61.25ms - 75.26ms
tip-of-tree tip-of-tree	698.01ms - 708.02ms	unsure 🔍 -1% - +1% -7.65ms - +5.88ms	-	faster ✔ 8% - 10% 61.83ms - 76.44ms
previous-release previous-release	766.83ms - 777.47ms	slower ❌ 9% - 11% 61.25ms - 75.26ms	slower ❌ 9% - 11% 61.83ms - 76.44ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	761.33ms - 772.98ms	-	unsure 🔍 -1% - +2% -5.20ms - +11.45ms	faster ✔ 3% - 5% 24.72ms - 40.89ms
tip-of-tree tip-of-tree	758.08ms - 769.98ms	unsure 🔍 -1% - +1% -11.45ms - +5.20ms	-	faster ✔ 3% - 5% 27.75ms - 44.10ms
previous-release previous-release	794.35ms - 805.56ms	slower ❌ 3% - 5% 24.72ms - 40.89ms	slower ❌ 4% - 6% 27.75ms - 44.10ms	-

lit-html-kitchen-sink

• Browser: chrome-headless 93.0.4577.63
• Sample size: 30
• Built by: Benchmarks #1946

• Commit: 6ab760a

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	34.80ms - 35.79ms	-	unsure 🔍 -1% - +2% -0.34ms - +0.70ms	faster ✔ 13% - 19% 5.47ms - 8.26ms
tip-of-tree tip-of-tree	34.97ms - 35.25ms	unsure 🔍 -2% - +1% -0.70ms - +0.34ms	-	faster ✔ 14% - 19% 5.74ms - 8.36ms
previous-release previous-release	40.86ms - 43.46ms	slower ❌ 15% - 24% 5.47ms - 8.26ms	slower ❌ 16% - 24% 5.74ms - 8.36ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	87.49ms - 89.92ms	-	unsure 🔍 -1% - +2% -1.23ms - +2.14ms	faster ✔ 4% - 8% 3.67ms - 7.93ms
tip-of-tree tip-of-tree	87.08ms - 89.42ms	unsure 🔍 -2% - +1% -2.14ms - +1.23ms	-	faster ✔ 4% - 9% 4.15ms - 8.36ms
previous-release previous-release	92.75ms - 96.26ms	slower ❌ 4% - 9% 3.67ms - 7.93ms	slower ❌ 5% - 10% 4.15ms - 8.36ms	-

nop-update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	28.57ms - 28.93ms	-	unsure 🔍 -1% - +0% -0.38ms - +0.11ms	faster ✔ 1% - 4% 0.40ms - 1.27ms
tip-of-tree tip-of-tree	28.73ms - 29.04ms	unsure 🔍 -0% - +1% -0.11ms - +0.38ms	-	faster ✔ 1% - 4% 0.28ms - 1.13ms
previous-release previous-release	29.19ms - 29.98ms	slower ❌ 1% - 4% 0.40ms - 1.27ms	slower ❌ 1% - 4% 0.28ms - 1.13ms	-

lit-html-repeat

• Browser: chrome-headless 93.0.4577.63
• Sample size: 30
• Built by: Benchmarks #1946

• Commit: 6ab760a

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	12.17ms - 12.47ms	-	unsure 🔍 -1% - +2% -0.14ms - +0.24ms	faster ✔ 6% - 9% 0.83ms - 1.15ms
tip-of-tree tip-of-tree	12.15ms - 12.39ms	unsure 🔍 -2% - +1% -0.24ms - +0.14ms	-	faster ✔ 7% - 9% 0.90ms - 1.18ms
previous-release previous-release	13.25ms - 13.37ms	slower ❌ 7% - 9% 0.83ms - 1.15ms	slower ❌ 7% - 10% 0.90ms - 1.18ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	352.67ms - 357.03ms	-	unsure 🔍 -1% - +1% -3.21ms - +3.27ms	faster ✔ 28% - 30% 140.37ms - 149.11ms
tip-of-tree tip-of-tree	352.43ms - 357.21ms	unsure 🔍 -1% - +1% -3.27ms - +3.21ms	-	faster ✔ 28% - 30% 140.29ms - 149.25ms
previous-release previous-release	495.80ms - 503.38ms	slower ❌ 39% - 42% 140.37ms - 149.11ms	slower ❌ 39% - 42% 140.29ms - 149.25ms	-

lit-html-template-heavy

• Browser: chrome-headless 93.0.4577.63
• Sample size: 50
• Built by: Benchmarks #1946

• Commit: 6ab760a

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	57.92ms - 58.58ms	-	unsure 🔍 -1% - +0% -0.83ms - +0.29ms	faster ✔ 16% - 17% 11.19ms - 12.28ms
tip-of-tree tip-of-tree	58.07ms - 58.97ms	unsure 🔍 -0% - +1% -0.29ms - +0.83ms	-	faster ✔ 16% - 17% 10.84ms - 12.09ms
previous-release previous-release	69.55ms - 70.42ms	slower ❌ 19% - 21% 11.19ms - 12.28ms	slower ❌ 18% - 21% 10.84ms - 12.09ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	122.17ms - 124.15ms	-	unsure 🔍 -2% - +1% -1.96ms - +1.11ms	faster ✔ 12% - 14% 16.20ms - 19.37ms
tip-of-tree tip-of-tree	122.41ms - 124.75ms	unsure 🔍 -1% - +2% -1.11ms - +1.96ms	-	faster ✔ 11% - 13% 15.65ms - 19.07ms
previous-release previous-release	139.70ms - 142.18ms	slower ❌ 13% - 16% 16.20ms - 19.37ms	slower ❌ 13% - 16% 15.65ms - 19.07ms	-

reactive-element-list

• Browser: chrome-headless 93.0.4577.63
• Sample size: 50
• Built by: Benchmarks #1946

• Commit: 6ab760a

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	58.00ms - 58.71ms	-	unsure 🔍 -1% - +1% -0.47ms - +0.69ms	unsure 🔍 -1% - +1% -0.56ms - +0.50ms
tip-of-tree tip-of-tree	57.79ms - 58.70ms	unsure 🔍 -1% - +1% -0.69ms - +0.47ms	-	unsure 🔍 -1% - +1% -0.74ms - +0.46ms
previous-release previous-release	57.99ms - 58.78ms	unsure 🔍 -1% - +1% -0.50ms - +0.56ms	unsure 🔍 -1% - +1% -0.46ms - +0.74ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	713.08ms - 721.74ms	-	unsure 🔍 -1% - +0% -9.28ms - +2.50ms	unsure 🔍 -1% - +1% -8.95ms - +3.88ms
tip-of-tree tip-of-tree	716.80ms - 724.80ms	unsure 🔍 -0% - +1% -2.50ms - +9.28ms	-	unsure 🔍 -1% - +1% -5.34ms - +7.05ms
previous-release previous-release	715.21ms - 724.68ms	unsure 🔍 -1% - +1% -3.88ms - +8.95ms	unsure 🔍 -1% - +1% -7.05ms - +5.34ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	808.66ms - 817.05ms	-	unsure 🔍 -1% - +1% -7.71ms - +4.59ms	unsure 🔍 -1% - +1% -6.29ms - +6.14ms
tip-of-tree tip-of-tree	809.93ms - 818.90ms	unsure 🔍 -1% - +1% -4.59ms - +7.71ms	-	unsure 🔍 -1% - +1% -4.93ms - +7.90ms
previous-release previous-release	808.35ms - 817.51ms	unsure 🔍 -1% - +1% -6.14ms - +6.29ms	unsure 🔍 -1% - +1% -7.90ms - +4.93ms	-

_{tachometer-reporter-action v2 for Benchmarks}

[aomarks]

Nice docs!

Link thing is optional -- maybe something we should do as a search/replace across everything.

[arthurevans]

LGTM. Added a few minor suggestions.

[justinfagnani]

Authors can definitely read this flag. It might be handy in custom getUpdateComplete implementations... so maybe instead of "Internal" just say that it's true if there's a pending update as a result of a requestUpdate() call and it should only be read.

[justinfagnani]

I'd remove the "required for..." and just say "The element cannot assume..."

[justinfagnani]

Add "If the element is connected when addController() is called, the controller's hostConnected() callback will be immediately called.

[AndrewJakubowicz]

Is this ok to merge with the failing tests? None of them seem related to jsdocs?

[aomarks]

Is this ok to merge with the failing tests? None of them seem related to jsdocs?

The changeset failure is because there's no changeset. Might actually make sense here, since it is a change to the distributed package, and a changeset will signal that there is a pending change that hasn't been released yet, and eventually make its way into the CHANGELOG. You can use npx changeset for a wizard that lets you create an entry.

I think the Sauce tests always fail, something has been up with those for weeks. IE11 busted? Not sure.

[aomarks]

The changeset failure is because there's no changeset. Might actually make sense here, since it is a change to the distributed package, and a changeset will signal that there is a pending change that hasn't been released yet, and eventually make its way into the CHANGELOG. You can use npx changeset for a wizard that lets you create an entry.

Just something general like "Additional documentation on Lit APIs" or something seems fine.