[lit-html] Expand documentation for `TemplateResult` and `render`. #2849

AndrewJakubowicz · 2022-05-09T18:19:44Z

Part of #1883

This is a documentation only PR which expands the jsdocs for render and TemplateResult.

Impact:

TemplateResult is used and referenced very often and has very minimal documentation. This documentation aims to explain what a TemplateResult is, and how to render it to DOM via the lit-html render function or the LitElement.render lifecycle method.
lit-html's render function is brilliant and lost some documentation between Lit 1 -> Lit 2.

To document these I referenced:

Our wiki page: https://github.com/lit/lit/wiki/How-it-Works#javascript-tagged-template-literals
Our Lit 1 documentation for render: https://lit.dev/docs/v1/lit-html/rendering-templates/
Our Lit 1 generated docs for render: https://lit.dev/docs/v1/api/lit-html/templates/#render
And the upgrade docs for render which document the container appending behavior.

Screenshots

For example render hover over:

changeset-bot · 2022-05-09T18:19:46Z

🦋 Changeset detected

Latest commit: f154b90

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-05-09T18:20:05Z

📊 Tachometer Benchmark Results

Summary

nop-update

lit-html-kitchen-sink: unsure 🔍 -4% - +8% (-1.16ms - +2.64ms)
^{this-change vs tip-of-tree}

render

lit-element-list: unsure 🔍 -3% - +1% (-3.08ms - +0.77ms)
^{this-change vs tip-of-tree}
lit-html-kitchen-sink: unsure 🔍 -3% - +2% (-1.24ms - +0.90ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -6% - +2% (-0.78ms - +0.24ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -1% - +5% (-0.90ms - +3.41ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -3% - +2% (-2.39ms - +1.34ms)
^{this-change vs tip-of-tree}

update

lit-element-list: unsure 🔍 -1% - +3% (-9.62ms - +36.09ms)
^{this-change vs tip-of-tree}
lit-html-kitchen-sink: unsure 🔍 -6% - +2% (-6.68ms - +2.60ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -5% - +2% (-23.78ms - +9.18ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -2% - +2% (-3.87ms - +4.37ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -2% - +11% (-23.73ms - +201.96ms)
^{this-change vs tip-of-tree}

update-reflect

lit-element-list: unsure 🔍 -1% - +1% (-13.89ms - +15.88ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -1% - +3% (-16.92ms - +40.29ms)
^{this-change vs tip-of-tree}

Results

lit-element-list

Browser: chrome-headless 102.0.5005.61
Sample size: 50
Built by: Benchmarks #3354
Commit: de55070

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	102.93ms - 105.29ms	-	unsure 🔍 -3% - +1% -3.08ms - +0.77ms	faster ✔ 22% - 24% 29.81ms - 33.37ms
tip-of-tree tip-of-tree	103.74ms - 106.79ms	unsure 🔍 -1% - +3% -0.77ms - +3.08ms	-	faster ✔ 21% - 24% 28.41ms - 32.46ms
previous-release previous-release	134.37ms - 137.03ms	slower ❌ 28% - 32% 29.81ms - 33.37ms	slower ❌ 27% - 31% 28.41ms - 32.46ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1051.09ms - 1094.66ms	-	unsure 🔍 -1% - +3% -9.62ms - +36.09ms	faster ✔ 32% - 35% 512.06ms - 573.90ms
tip-of-tree tip-of-tree	1052.74ms - 1066.53ms	unsure 🔍 -3% - +1% -36.09ms - +9.62ms	-	faster ✔ 33% - 35% 533.22ms - 579.21ms
previous-release previous-release	1593.91ms - 1637.79ms	slower ❌ 47% - 54% 512.06ms - 573.90ms	slower ❌ 50% - 55% 533.22ms - 579.21ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1072.56ms - 1091.66ms	-	unsure 🔍 -1% - +1% -13.89ms - +15.88ms	faster ✔ 7% - 9% 82.86ms - 111.21ms
tip-of-tree tip-of-tree	1069.71ms - 1092.53ms	unsure 🔍 -1% - +1% -15.88ms - +13.89ms	-	faster ✔ 7% - 10% 82.54ms - 113.52ms
previous-release previous-release	1168.68ms - 1189.62ms	slower ❌ 8% - 10% 82.86ms - 111.21ms	slower ❌ 8% - 11% 82.54ms - 113.52ms	-

lit-html-kitchen-sink

Browser: chrome-headless 102.0.5005.61
Sample size: 30
Built by: Benchmarks #3354
Commit: de55070

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	43.49ms - 44.84ms	-	unsure 🔍 -3% - +2% -1.24ms - +0.90ms	faster ✔ 8% - 14% 3.67ms - 7.09ms
tip-of-tree tip-of-tree	43.50ms - 45.17ms	unsure 🔍 -2% - +3% -0.90ms - +1.24ms	-	faster ✔ 7% - 14% 3.42ms - 7.00ms
previous-release previous-release	47.97ms - 51.12ms	slower ❌ 8% - 16% 3.67ms - 7.09ms	slower ❌ 8% - 16% 3.42ms - 7.00ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	110.96ms - 115.78ms	-	unsure 🔍 -6% - +2% -6.68ms - +2.60ms	unsure 🔍 -5% - +1% -5.61ms - +1.56ms
tip-of-tree tip-of-tree	111.44ms - 119.37ms	unsure 🔍 -2% - +6% -2.60ms - +6.68ms	-	unsure 🔍 -4% - +4% -4.76ms - +4.79ms
previous-release previous-release	112.73ms - 118.05ms	unsure 🔍 -1% - +5% -1.56ms - +5.61ms	unsure 🔍 -4% - +4% -4.79ms - +4.76ms	-

nop-update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	32.17ms - 35.84ms	-	unsure 🔍 -4% - +8% -1.16ms - +2.64ms	faster ✔ 0% - 11% 0.10ms - 4.05ms
tip-of-tree tip-of-tree	32.76ms - 33.77ms	unsure 🔍 -8% - +3% -2.64ms - +1.16ms	-	faster ✔ 5% - 10% 1.93ms - 3.70ms
previous-release previous-release	35.35ms - 36.81ms	unsure 🔍 -0% - +12% +0.10ms - +4.05ms	slower ❌ 6% - 11% 1.93ms - 3.70ms	-

lit-html-repeat

Browser: chrome-headless 102.0.5005.61
Sample size: 30
Built by: Benchmarks #3354
Commit: de55070

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	13.33ms - 13.90ms	-	unsure 🔍 -6% - +2% -0.78ms - +0.24ms	faster ✔ 9% - 14% 1.37ms - 2.10ms
tip-of-tree tip-of-tree	13.46ms - 14.31ms	unsure 🔍 -2% - +6% -0.24ms - +0.78ms	-	faster ✔ 6% - 13% 0.98ms - 1.95ms
previous-release previous-release	15.13ms - 15.58ms	slower ❌ 10% - 16% 1.37ms - 2.10ms	slower ❌ 7% - 14% 0.98ms - 1.95ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	454.70ms - 481.72ms	-	unsure 🔍 -5% - +2% -23.78ms - +9.18ms	faster ✔ 22% - 27% 137.03ms - 169.30ms
tip-of-tree tip-of-tree	466.06ms - 484.95ms	unsure 🔍 -2% - +5% -9.18ms - +23.78ms	-	faster ✔ 22% - 25% 132.94ms - 158.78ms
previous-release previous-release	612.55ms - 630.19ms	slower ❌ 28% - 37% 137.03ms - 169.30ms	slower ❌ 27% - 34% 132.94ms - 158.78ms	-

lit-html-template-heavy

Browser: chrome-headless 102.0.5005.61
Sample size: 50
Built by: Benchmarks #3354
Commit: de55070

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	74.70ms - 77.80ms	-	unsure 🔍 -1% - +5% -0.90ms - +3.41ms	faster ✔ 11% - 16% 9.72ms - 13.91ms
tip-of-tree tip-of-tree	73.49ms - 76.50ms	unsure 🔍 -4% - +1% -3.41ms - +0.90ms	-	faster ✔ 13% - 17% 11.01ms - 15.13ms
previous-release previous-release	86.66ms - 89.47ms	slower ❌ 13% - 18% 9.72ms - 13.91ms	slower ❌ 14% - 20% 11.01ms - 15.13ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	172.83ms - 178.54ms	-	unsure 🔍 -2% - +2% -3.87ms - +4.37ms	faster ✔ 9% - 13% 18.28ms - 26.38ms
tip-of-tree tip-of-tree	172.47ms - 178.40ms	unsure 🔍 -2% - +2% -4.37ms - +3.87ms	-	faster ✔ 9% - 13% 18.45ms - 26.71ms
previous-release previous-release	195.15ms - 200.89ms	slower ❌ 10% - 15% 18.28ms - 26.38ms	slower ❌ 10% - 15% 18.45ms - 26.71ms	-

reactive-element-list

Browser: chrome-headless 102.0.5005.61
Sample size: 50
Built by: Benchmarks #3354
Commit: de55070

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	76.20ms - 78.64ms	-	unsure 🔍 -3% - +2% -2.39ms - +1.34ms	unsure 🔍 -3% - +3% -2.59ms - +2.66ms
tip-of-tree tip-of-tree	76.54ms - 79.35ms	unsure 🔍 -2% - +3% -1.34ms - +2.39ms	-	unsure 🔍 -3% - +4% -2.15ms - +3.28ms
previous-release previous-release	75.06ms - 79.71ms	unsure 🔍 -3% - +3% -2.66ms - +2.59ms	unsure 🔍 -4% - +3% -3.28ms - +2.15ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1832.45ms - 1959.30ms	-	unsure 🔍 -2% - +11% -23.73ms - +201.96ms	unsure 🔍 -3% - +10% -45.49ms - +177.39ms
tip-of-tree tip-of-tree	1713.43ms - 1900.09ms	unsure 🔍 -11% - +1% -201.96ms - +23.73ms	-	unsure 🔍 -8% - +6% -153.95ms - +107.63ms
previous-release previous-release	1738.29ms - 1921.55ms	unsure 🔍 -9% - +2% -177.39ms - +45.49ms	unsure 🔍 -6% - +9% -107.63ms - +153.95ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1171.22ms - 1207.53ms	-	unsure 🔍 -1% - +3% -16.92ms - +40.29ms	unsure 🔍 -2% - +3% -25.99ms - +31.06ms
tip-of-tree tip-of-tree	1155.58ms - 1199.79ms	unsure 🔍 -3% - +1% -40.29ms - +16.92ms	-	unsure 🔍 -3% - +2% -40.34ms - +22.04ms
previous-release previous-release	1164.84ms - 1208.84ms	unsure 🔍 -3% - +2% -31.06ms - +25.99ms	unsure 🔍 -2% - +3% -22.04ms - +40.34ms	-

_{tachometer-reporter-action v2 for Benchmarks}

…eResult

packages/lit-html/src/lit-html.ts

…lpful.

augustjk

LGTM

arthurevans · 2022-06-10T06:51:36Z

packages/lit-html/src/lit-html.ts

- * @param options
+ *
+ * For example, to render "Hello, Zoe!" to the container `document.body` where
+ * the name "Zoe" is from a variable:


Maybe to @justinfagnani 's point, this should say something like,

This example renders the text "Hello, Zoe!" inside a paragraph tag, appending it to the container document.body.

Thank you! Adding verbatim.

arthurevans

One small suggestion, otherwise LGTM.

AndrewJakubowicz added 2 commits May 9, 2022 11:12

Add render and TemplateResult documentation.

f9a1c99

Add changeset

49fb48e

Add small amount of documentation to describe how to render a Templat…

e276e50

…eResult

AndrewJakubowicz force-pushed the template-result-docs branch from 42fc198 to e276e50 Compare May 9, 2022 18:34

AndrewJakubowicz marked this pull request as ready for review May 9, 2022 18:54

AndrewJakubowicz requested a review from justinfagnani as a code owner May 9, 2022 18:54

AndrewJakubowicz requested a review from arthurevans May 9, 2022 18:55

justinfagnani requested changes May 13, 2022

View reviewed changes

packages/lit-html/src/lit-html.ts Outdated Show resolved Hide resolved

packages/lit-html/src/lit-html.ts Outdated Show resolved Hide resolved

packages/lit-html/src/lit-html.ts Outdated Show resolved Hide resolved

Code review feedback

4f27638

AndrewJakubowicz requested a review from justinfagnani May 16, 2022 19:22

Merge branch 'main' of github.com:lit/lit into template-result-docs

69d7e2f

AndrewJakubowicz self-assigned this Jun 8, 2022

Code review feedback: add back variable into example. I think it's he…

2717a5f

…lpful.

augustjk approved these changes Jun 8, 2022

View reviewed changes

arthurevans reviewed Jun 10, 2022

View reviewed changes

arthurevans approved these changes Jun 10, 2022

View reviewed changes

Code review feedback

15de742

AndrewJakubowicz mentioned this pull request Jun 10, 2022

[all] Expand jsdoc documentation #1883

Open

justinfagnani approved these changes Jun 10, 2022

View reviewed changes

AndrewJakubowicz added 2 commits June 10, 2022 09:17

Merge branch 'main' of github.com:lit/lit into template-result-docs

eca93a8

Merge branch 'main' of github.com:lit/lit into template-result-docs

d5d58a9

AndrewJakubowicz enabled auto-merge (squash) June 10, 2022 21:53

Merge branch 'main' into template-result-docs

f154b90

AndrewJakubowicz merged commit b12e8d9 into main Jun 10, 2022

AndrewJakubowicz deleted the template-result-docs branch June 10, 2022 22:26

lit-robot mentioned this pull request Jun 13, 2022

Version Packages #3028

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[lit-html] Expand documentation for `TemplateResult` and `render`. #2849

[lit-html] Expand documentation for `TemplateResult` and `render`. #2849

AndrewJakubowicz commented May 9, 2022 •

edited

changeset-bot bot commented May 9, 2022 •

edited

github-actions bot commented May 9, 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 Jun 10, 2022

AndrewJakubowicz Jun 10, 2022

arthurevans left a comment

[lit-html] Expand documentation for TemplateResult and render. #2849

[lit-html] Expand documentation for TemplateResult and render. #2849

Conversation

AndrewJakubowicz commented May 9, 2022 • edited

Screenshots

changeset-bot bot commented May 9, 2022 • edited

🦋 Changeset detected

github-actions bot commented May 9, 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 Jun 10, 2022

Choose a reason for hiding this comment

AndrewJakubowicz Jun 10, 2022

Choose a reason for hiding this comment

arthurevans left a comment

Choose a reason for hiding this comment

[lit-html] Expand documentation for `TemplateResult` and `render`. #2849

[lit-html] Expand documentation for `TemplateResult` and `render`. #2849

AndrewJakubowicz commented May 9, 2022 •

edited

changeset-bot bot commented May 9, 2022 •

edited

github-actions bot commented May 9, 2022 •

edited