Fix documentation examples so they have syntax highlighting #2050

AndrewJakubowicz · 2021-08-13T18:36:56Z

Context

Lit.dev pulls the API documentation out of the jsDoc comments. While auditing lit.dev I found some examples that aren't rendering correctly. Some of these examples also don't render correctly in the IDE. This is a small cleanup PR that unifies the example syntax.

Why

Fixes some example code in the jsDocs on both lit.dev and hover IDE documentation, i.e.

How

There is two kinds of example syntax I could identify in the codebase. Inline triple backticks with a language annotation, and the @example attribute.
Currently lit.dev doesn't render the @example attribute (Filed: lit/lit.dev#434), but does render inline code fences. Updated docs to use code fences with language declaration.

Testing

Tested manually in VS code by hovering over the properties and eyeballing the tooltips. Risk should be very minor as this is a small documentation cleanup.

changeset-bot · 2021-08-13T18:36:58Z

⚠️ No Changeset found

Latest commit: 89dfcc1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2021-08-13T18:37:18Z

📊 Tachometer Benchmark Results

Summary

nop-update

lit-html-kitchen-sink: unsure 🔍 -4% - +3% (-1.54ms - +1.32ms)
^{this-change vs tip-of-tree}

render

lit-element-list: unsure 🔍 -1% - +3% (-0.75ms - +3.16ms)
^{this-change vs tip-of-tree}
lit-html-kitchen-sink: unsure 🔍 -3% - +2% (-1.52ms - +0.89ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -3% - +4% (-0.53ms - +0.71ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -3% - +1% (-2.58ms - +1.15ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -1% - +3% (-1.00ms - +2.82ms)
^{this-change vs tip-of-tree}

update

lit-element-list: unsure 🔍 -1% - +1% (-10.59ms - +15.66ms)
^{this-change vs tip-of-tree}
lit-html-kitchen-sink: unsure 🔍 -4% - +2% (-5.09ms - +2.75ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -1% - +2% (-4.62ms - +11.25ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -3% - +2% (-4.62ms - +4.21ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -2% - +2% (-23.55ms - +25.49ms)
^{this-change vs tip-of-tree}

update-reflect

lit-element-list: unsure 🔍 -1% - +2% (-10.48ms - +21.36ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -2% - +2% (-20.42ms - +26.88ms)
^{this-change vs tip-of-tree}

Results

lit-element-list

Browser: chrome-headless 92.0.4515.131
Sample size: 50
Built by: Benchmarks #1652
Commit: 68220ec

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	120.87ms - 123.77ms	-	unsure 🔍 -1% - +3% -0.75ms - +3.16ms	faster ✔ 22% - 25% 35.00ms - 40.45ms
tip-of-tree tip-of-tree	119.80ms - 122.43ms	unsure 🔍 -3% - +1% -3.16ms - +0.75ms	-	faster ✔ 23% - 26% 36.27ms - 41.59ms
previous-release previous-release	157.74ms - 162.35ms	slower ❌ 28% - 33% 35.00ms - 40.45ms	slower ❌ 30% - 35% 36.27ms - 41.59ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1053.36ms - 1072.93ms	-	unsure 🔍 -1% - +1% -10.59ms - +15.66ms	faster ✔ 7% - 9% 75.32ms - 105.21ms
tip-of-tree tip-of-tree	1051.86ms - 1069.36ms	unsure 🔍 -1% - +1% -15.66ms - +10.59ms	-	faster ✔ 7% - 9% 78.52ms - 107.08ms
previous-release previous-release	1142.12ms - 1164.70ms	slower ❌ 7% - 10% 75.32ms - 105.21ms	slower ❌ 7% - 10% 78.52ms - 107.08ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1079.25ms - 1101.71ms	-	unsure 🔍 -1% - +2% -10.48ms - +21.36ms	faster ✔ 4% - 7% 44.89ms - 78.74ms
tip-of-tree tip-of-tree	1073.76ms - 1096.32ms	unsure 🔍 -2% - +1% -21.36ms - +10.48ms	-	faster ✔ 4% - 7% 50.30ms - 84.22ms
previous-release previous-release	1139.64ms - 1164.96ms	slower ❌ 4% - 7% 44.89ms - 78.74ms	slower ❌ 5% - 8% 50.30ms - 84.22ms	-

lit-html-kitchen-sink

Browser: chrome-headless 92.0.4515.131
Sample size: 30
Built by: Benchmarks #1652
Commit: 68220ec

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	46.13ms - 47.78ms	-	unsure 🔍 -3% - +2% -1.52ms - +0.89ms	faster ✔ 18% - 23% 10.25ms - 13.86ms
tip-of-tree tip-of-tree	46.40ms - 48.14ms	unsure 🔍 -2% - +3% -0.89ms - +1.52ms	-	faster ✔ 17% - 23% 9.91ms - 13.57ms
previous-release previous-release	57.40ms - 60.61ms	slower ❌ 22% - 30% 10.25ms - 13.86ms	slower ❌ 21% - 29% 9.91ms - 13.57ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	121.90ms - 125.90ms	-	unsure 🔍 -4% - +2% -5.09ms - +2.75ms	faster ✔ 4% - 10% 5.52ms - 12.99ms
tip-of-tree tip-of-tree	121.70ms - 128.43ms	unsure 🔍 -2% - +4% -2.75ms - +5.09ms	-	faster ✔ 3% - 9% 3.47ms - 12.70ms
previous-release previous-release	130.00ms - 136.31ms	slower ❌ 4% - 11% 5.52ms - 12.99ms	slower ❌ 3% - 10% 3.47ms - 12.70ms	-

nop-update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	41.38ms - 43.32ms	-	unsure 🔍 -4% - +3% -1.54ms - +1.32ms	unsure 🔍 -4% - +6% -1.63ms - +2.35ms
tip-of-tree tip-of-tree	41.41ms - 43.51ms	unsure 🔍 -3% - +4% -1.32ms - +1.54ms	-	unsure 🔍 -4% - +6% -1.57ms - +2.50ms
previous-release previous-release	40.25ms - 43.73ms	unsure 🔍 -6% - +4% -2.35ms - +1.63ms	unsure 🔍 -6% - +4% -2.50ms - +1.57ms	-

lit-html-repeat

Browser: chrome-headless 92.0.4515.131
Sample size: 30
Built by: Benchmarks #1652
Commit: 68220ec

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	15.78ms - 16.53ms	-	unsure 🔍 -3% - +4% -0.53ms - +0.71ms	faster ✔ 10% - 16% 1.87ms - 2.91ms
tip-of-tree tip-of-tree	15.57ms - 16.56ms	unsure 🔍 -4% - +3% -0.71ms - +0.53ms	-	faster ✔ 10% - 17% 1.86ms - 3.09ms
previous-release previous-release	18.18ms - 18.91ms	slower ❌ 11% - 18% 1.87ms - 2.91ms	slower ❌ 11% - 20% 1.86ms - 3.09ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	491.46ms - 502.11ms	-	unsure 🔍 -1% - +2% -4.62ms - +11.25ms	faster ✔ 27% - 29% 180.53ms - 197.27ms
tip-of-tree tip-of-tree	487.60ms - 499.35ms	unsure 🔍 -2% - +1% -11.25ms - +4.62ms	-	faster ✔ 27% - 29% 183.48ms - 200.94ms
previous-release previous-release	679.23ms - 692.14ms	slower ❌ 36% - 40% 180.53ms - 197.27ms	slower ❌ 37% - 41% 183.48ms - 200.94ms	-

lit-html-template-heavy

Browser: chrome-headless 92.0.4515.131
Sample size: 50
Built by: Benchmarks #1652
Commit: 68220ec

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	82.33ms - 84.94ms	-	unsure 🔍 -3% - +1% -2.58ms - +1.15ms	faster ✔ 16% - 20% 15.97ms - 20.83ms
tip-of-tree tip-of-tree	83.01ms - 85.69ms	unsure 🔍 -1% - +3% -1.15ms - +2.58ms	-	faster ✔ 15% - 19% 15.24ms - 20.13ms
previous-release previous-release	99.99ms - 104.08ms	slower ❌ 19% - 25% 15.97ms - 20.83ms	slower ❌ 18% - 24% 15.24ms - 20.13ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	178.82ms - 185.47ms	-	unsure 🔍 -3% - +2% -4.62ms - +4.21ms	faster ✔ 10% - 14% 19.75ms - 29.10ms
tip-of-tree tip-of-tree	179.45ms - 185.25ms	unsure 🔍 -2% - +3% -4.21ms - +4.62ms	-	faster ✔ 10% - 14% 19.84ms - 28.60ms
previous-release previous-release	203.29ms - 209.86ms	slower ❌ 11% - 16% 19.75ms - 29.10ms	slower ❌ 11% - 16% 19.84ms - 28.60ms	-

reactive-element-list

Browser: chrome-headless 92.0.4515.131
Sample size: 50
Built by: Benchmarks #1652
Commit: 68220ec

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	80.85ms - 83.85ms	-	unsure 🔍 -1% - +3% -1.00ms - +2.82ms	unsure 🔍 -2% - +3% -1.60ms - +2.44ms
tip-of-tree tip-of-tree	80.26ms - 82.61ms	unsure 🔍 -3% - +1% -2.82ms - +1.00ms	-	unsure 🔍 -3% - +2% -2.29ms - +1.29ms
previous-release previous-release	80.58ms - 83.28ms	unsure 🔍 -3% - +2% -2.44ms - +1.60ms	unsure 🔍 -2% - +3% -1.29ms - +2.29ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1044.43ms - 1078.57ms	-	unsure 🔍 -2% - +2% -23.55ms - +25.49ms	unsure 🔍 -2% - +3% -20.36ms - +27.73ms
tip-of-tree tip-of-tree	1042.92ms - 1078.13ms	unsure 🔍 -2% - +2% -25.49ms - +23.55ms	-	unsure 🔍 -2% - +3% -21.71ms - +27.13ms
previous-release previous-release	1040.89ms - 1074.74ms	unsure 🔍 -3% - +2% -27.73ms - +20.36ms	unsure 🔍 -3% - +2% -27.13ms - +21.71ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1119.74ms - 1153.63ms	-	unsure 🔍 -2% - +2% -20.42ms - +26.88ms	unsure 🔍 -2% - +2% -26.11ms - +22.73ms
tip-of-tree tip-of-tree	1116.96ms - 1149.96ms	unsure 🔍 -2% - +2% -26.88ms - +20.42ms	-	unsure 🔍 -3% - +2% -29.03ms - +19.19ms
previous-release previous-release	1120.80ms - 1155.95ms	unsure 🔍 -2% - +2% -22.73ms - +26.11ms	unsure 🔍 -2% - +3% -19.19ms - +29.03ms	-

_{tachometer-reporter-action v2 for Benchmarks}

aomarks

Nice!

* Add SSR global demo changeset * Add changeset for types cleanup * Add CSSResult check changeset * Add changeset for #1937 * Add changeset for #1943 * Add changeset for #1964 * Add changeset for #2050 * Add missing changesets Co-authored-by: Kevin Schaaf <kschaaf@google.com>

AndrewJakubowicz requested a review from justinfagnani as a code owner August 13, 2021 18:36

google-cla bot added the cla: yes label Aug 13, 2021

Fix documentation examples so they have syntax highlighting.

89dfcc1

AndrewJakubowicz force-pushed the litdev-examples-cleanup branch from b3d9473 to 89dfcc1 Compare August 13, 2021 18:42

aomarks approved these changes Aug 13, 2021

View reviewed changes

justinfagnani approved these changes Aug 16, 2021

View reviewed changes

AndrewJakubowicz merged commit 8758e06 into main Aug 16, 2021

AndrewJakubowicz deleted the litdev-examples-cleanup branch August 16, 2021 21:25

AndrewJakubowicz mentioned this pull request Aug 17, 2021

Unify code examples by removing @example attribute. #2054

Merged

justinfagnani added a commit that referenced this pull request Aug 19, 2021

Add changeset for #2050

b0377a5

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix documentation examples so they have syntax highlighting #2050

Fix documentation examples so they have syntax highlighting #2050

AndrewJakubowicz commented Aug 13, 2021 •

edited

changeset-bot bot commented Aug 13, 2021 •

edited

github-actions bot commented Aug 13, 2021 •

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

aomarks left a comment

Fix documentation examples so they have syntax highlighting #2050

Fix documentation examples so they have syntax highlighting #2050

Conversation

AndrewJakubowicz commented Aug 13, 2021 • edited

Context

Why

How

Testing

changeset-bot bot commented Aug 13, 2021 • edited

⚠️ No Changeset found

github-actions bot commented Aug 13, 2021 • 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

aomarks left a comment

Choose a reason for hiding this comment

AndrewJakubowicz commented Aug 13, 2021 •

edited

changeset-bot bot commented Aug 13, 2021 •

edited

github-actions bot commented Aug 13, 2021 •

edited