[localize] Fix and document msgdesc comments

[aomarks]

• Fix an XML serialization bug that broke // msgdesc: comments.
• Add some test cases.
• Document them in the README.
• Fix incorrect README transform vs runtime table.

Fixes #1444

[github-actions]

📊 Tachometer Benchmark Results

Summary

nop-update

• ⏱ lit-html-kitchen-sink: unsure 🔍 -4% - +6% (-1.29ms - +2.12ms)
  ^{this-change vs tip-of-tree}

render

• ⏱ lit-element-list: unsure 🔍 -0% - +1% (-0.26ms - +0.99ms)
  ^{this-change vs tip-of-tree}
• ⏱ lit-html-kitchen-sink: unsure 🔍 -1% - +0% (-0.39ms - +0.15ms)
  ^{this-change vs tip-of-tree}
• ⏱ lit-html-repeat: unsure 🔍 -1% - +1% (-0.07ms - +0.08ms)
  ^{this-change vs tip-of-tree}
• ⏱ lit-html-template-heavy: unsure 🔍 -0% - +2% (-0.32ms - +1.15ms)
  ^{this-change vs tip-of-tree}
• ⏱ updating-element-list: unsure 🔍 -1% - +0% (-0.94ms - +0.22ms)
  ^{this-change vs tip-of-tree}

update

• ⏱ lit-element-list: slower ❌ 0% - 1% (0.14ms - 12.82ms)
  ^{this-change vs tip-of-tree}
• ⏱ lit-html-kitchen-sink: unsure 🔍 -3% - +2% (-3.00ms - +2.36ms)
  ^{this-change vs tip-of-tree}
• ⏱ lit-html-repeat: unsure 🔍 -1% - +1% (-2.28ms - +1.97ms)
  ^{this-change vs tip-of-tree}
• ⏱ lit-html-template-heavy: unsure 🔍 -1% - +2% (-1.35ms - +2.57ms)
  ^{this-change vs tip-of-tree}
• ⏱ updating-element-list: unsure 🔍 -1% - +1% (-6.73ms - +11.58ms)
  ^{this-change vs tip-of-tree}

update-reflect

• ⏱ lit-element-list: unsure 🔍 -0% - +1% (-4.49ms - +9.21ms)
  ^{this-change vs tip-of-tree}
• ⏱ updating-element-list: unsure 🔍 -1% - +1% (-12.30ms - +8.02ms)
  ^{this-change vs tip-of-tree}

Results

⏱ lit-element-list

• Browser: chrome-headless 86.0.4240.198
• Sample size: 50
• Built by: Benchmarks #609

• Commit: 9d82c91

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	93.05ms - 94.09ms	-	unsure 🔍 -0% - +1% -0.26ms - +0.99ms	faster ✔ 22% - 24% 27.25ms - 28.83ms
tip-of-tree tip-of-tree	92.87ms - 93.54ms	unsure 🔍 -1% - +0% -0.99ms - +0.26ms	-	faster ✔ 23% - 24% 27.72ms - 29.08ms
previous-release previous-release	121.01ms - 122.20ms	slower ❌ 29% - 31% 27.25ms - 28.83ms	slower ❌ 30% - 31% 27.72ms - 29.08ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	895.38ms - 904.48ms	-	slower ❌ 0% - 1% 0.14ms - 12.82ms	faster ✔ 7% - 8% 68.52ms - 82.37ms
tip-of-tree tip-of-tree	889.04ms - 897.87ms	faster ✔ 0% - 1% 0.14ms - 12.82ms	-	faster ✔ 8% - 9% 75.08ms - 88.77ms
previous-release previous-release	970.15ms - 980.60ms	slower ❌ 8% - 9% 68.52ms - 82.37ms	slower ❌ 8% - 10% 75.08ms - 88.77ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	968.32ms - 978.19ms	-	unsure 🔍 -0% - +1% -4.49ms - +9.21ms	faster ✔ 4% - 5% 38.03ms - 53.17ms
tip-of-tree tip-of-tree	966.14ms - 975.64ms	unsure 🔍 -1% - +0% -9.21ms - +4.49ms	-	faster ✔ 4% - 5% 40.51ms - 55.41ms
previous-release previous-release	1013.11ms - 1024.60ms	slower ❌ 4% - 5% 38.03ms - 53.17ms	slower ❌ 4% - 6% 40.51ms - 55.41ms	-

⏱ lit-html-kitchen-sink

• Browser: chrome-headless 86.0.4240.198
• Sample size: 30
• Built by: Benchmarks #609

• Commit: 9d82c91

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	37.98ms - 38.24ms	-	unsure 🔍 -1% - +0% -0.39ms - +0.15ms	faster ✔ 20% - 22% 9.52ms - 10.55ms
tip-of-tree tip-of-tree	37.99ms - 38.47ms	unsure 🔍 -0% - +1% -0.15ms - +0.39ms	-	faster ✔ 20% - 22% 9.36ms - 10.46ms
previous-release previous-release	47.64ms - 48.63ms	slower ❌ 25% - 28% 9.52ms - 10.55ms	slower ❌ 24% - 27% 9.36ms - 10.46ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	94.48ms - 98.27ms	-	unsure 🔍 -3% - +2% -3.00ms - +2.36ms	unsure 🔍 -2% - +3% -1.72ms - +2.87ms
tip-of-tree tip-of-tree	94.80ms - 98.58ms	unsure 🔍 -2% - +3% -2.36ms - +3.00ms	-	unsure 🔍 -1% - +3% -1.40ms - +3.19ms
previous-release previous-release	94.50ms - 97.09ms	unsure 🔍 -3% - +2% -2.87ms - +1.72ms	unsure 🔍 -3% - +1% -3.19ms - +1.40ms	-

nop-update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	32.72ms - 35.90ms	-	unsure 🔍 -4% - +6% -1.29ms - +2.12ms	unsure 🔍 -12% - +0% -4.35ms - +0.08ms
tip-of-tree tip-of-tree	33.27ms - 34.52ms	unsure 🔍 -6% - +4% -2.12ms - +1.29ms	-	faster ✔ 3% - 11% 0.89ms - 4.21ms
previous-release previous-release	34.91ms - 37.98ms	unsure 🔍 -0% - +13% -0.08ms - +4.35ms	slower ❌ 3% - 12% 0.89ms - 4.21ms	-

⏱ lit-html-repeat

• Browser: chrome-headless 86.0.4240.198
• Sample size: 30
• Built by: Benchmarks #609

• Commit: 9d82c91

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	12.01ms - 12.12ms	-	unsure 🔍 -1% - +1% -0.07ms - +0.08ms	faster ✔ 18% - 19% 2.74ms - 2.90ms
tip-of-tree tip-of-tree	12.01ms - 12.10ms	unsure 🔍 -1% - +1% -0.08ms - +0.07ms	-	faster ✔ 19% - 19% 2.76ms - 2.90ms
previous-release previous-release	14.83ms - 14.94ms	slower ❌ 23% - 24% 2.74ms - 2.90ms	slower ❌ 23% - 24% 2.76ms - 2.90ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	363.87ms - 366.94ms	-	unsure 🔍 -1% - +1% -2.28ms - +1.97ms	faster ✔ 31% - 33% 167.90ms - 175.95ms
tip-of-tree tip-of-tree	364.09ms - 367.03ms	unsure 🔍 -1% - +1% -1.97ms - +2.28ms	-	faster ✔ 31% - 33% 167.77ms - 175.78ms
previous-release previous-release	533.61ms - 541.06ms	slower ❌ 46% - 48% 167.90ms - 175.95ms	slower ❌ 46% - 48% 167.77ms - 175.78ms	-

⏱ lit-html-template-heavy

• Browser: chrome-headless 86.0.4240.198
• Sample size: 50
• Built by: Benchmarks #609

• Commit: 9d82c91

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	67.15ms - 68.04ms	-	unsure 🔍 -0% - +2% -0.32ms - +1.15ms	faster ✔ 14% - 16% 11.02ms - 12.55ms
tip-of-tree tip-of-tree	66.59ms - 67.77ms	unsure 🔍 -2% - +0% -1.15ms - +0.32ms	-	faster ✔ 14% - 16% 11.34ms - 13.06ms
previous-release previous-release	78.76ms - 80.01ms	slower ❌ 16% - 19% 11.02ms - 12.55ms	slower ❌ 17% - 20% 11.34ms - 13.06ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	139.89ms - 142.63ms	-	unsure 🔍 -1% - +2% -1.35ms - +2.57ms	faster ✔ 13% - 16% 21.38ms - 25.94ms
tip-of-tree tip-of-tree	139.24ms - 142.04ms	unsure 🔍 -2% - +1% -2.57ms - +1.35ms	-	faster ✔ 13% - 16% 21.97ms - 26.57ms
previous-release previous-release	163.09ms - 166.74ms	slower ❌ 15% - 18% 21.38ms - 25.94ms	slower ❌ 16% - 19% 21.97ms - 26.57ms	-

⏱ updating-element-list

• Browser: chrome-headless 86.0.4240.198
• Sample size: 50
• Built by: Benchmarks #609

• Commit: 9d82c91

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	66.89ms - 67.63ms	-	unsure 🔍 -1% - +0% -0.94ms - +0.22ms	unsure 🔍 -1% - +1% -0.53ms - +0.55ms
tip-of-tree tip-of-tree	67.17ms - 68.07ms	unsure 🔍 -0% - +1% -0.22ms - +0.94ms	-	unsure 🔍 -0% - +1% -0.22ms - +0.96ms
previous-release previous-release	66.86ms - 67.64ms	unsure 🔍 -1% - +1% -0.55ms - +0.53ms	unsure 🔍 -1% - +0% -0.96ms - +0.22ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	935.97ms - 949.89ms	-	unsure 🔍 -1% - +1% -6.73ms - +11.58ms	unsure 🔍 -1% - +1% -7.37ms - +10.53ms
tip-of-tree tip-of-tree	934.56ms - 946.45ms	unsure 🔍 -1% - +1% -11.58ms - +6.73ms	-	unsure 🔍 -1% - +1% -9.03ms - +7.34ms
previous-release previous-release	935.72ms - 946.98ms	unsure 🔍 -1% - +1% -10.53ms - +7.37ms	unsure 🔍 -1% - +1% -7.34ms - +9.03ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1029.20ms - 1044.88ms	-	unsure 🔍 -1% - +1% -12.30ms - +8.02ms	unsure 🔍 -1% - +1% -13.95ms - +6.74ms
tip-of-tree tip-of-tree	1032.72ms - 1045.65ms	unsure 🔍 -1% - +1% -8.02ms - +12.30ms	-	unsure 🔍 -1% - +1% -10.81ms - +7.89ms
previous-release previous-release	1033.89ms - 1047.40ms	unsure 🔍 -1% - +1% -6.74ms - +13.95ms	unsure 🔍 -1% - +1% -7.89ms - +10.81ms	-

_{tachometer-reporter-action v2 for Benchmarks}

[justinfagnani]

ouch!

Can you remove the "DOM" lib from the tsconfig? Hopefully TS would catch this.

[aomarks]

Done. (But DOM types still get loaded because the xmldom package I'm loading has a reference to them)

[justinfagnani]

Filed an issue here: DefinitelyTyped/DefinitelyTyped#49953