[lit-html] Add svg tagged template literal documentation (#2479)

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

.changeset/silly-donuts-sit.md

@@ -0,0 +1,6 @@
+---
+'lit-html': patch
+'lit': patch
+---
+
+Expand JSDocs for the `svg` tagged template literal (TTL). The new documentation makes it more clear that the `svg` tag function should only be used for SVG fragments, and not for the `<svg>` HTML element.

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

@@ -323,8 +323,27 @@ const tag =
 export const html = tag(HTML_RESULT);
 
 /**
- * Interprets a template literal as an SVG template that can efficiently
+ * Interprets a template literal as an SVG fragment that can efficiently
  * render to and update a container.
+ *
+ * ```ts
+ * const rect = svg`<rect width="10" height="10"></rect>`;
+ *
+ * const myImage = html`
+ *   <svg viewBox="0 0 10 10" xmlns="http://www.w3.org/2000/svg">
+ *     ${rect}
+ *   </svg>`;
+ * ```
+ *
+ * The `svg` *tag function* should only be used for SVG fragments, or elements
+ * that would be contained **inside** an `<svg>` HTML element. A common error is
+ * placing an `<svg>` *element* in a template tagged with the `svg` tag
+ * function. The `<svg>` element is an HTML element and should be used within a
+ * template tagged with the {@linkcode html} tag function.
+ *
+ * In LitElement usage, it's rare to return an SVG fragment from the `render()`
+ * method, as the SVG fragment will be contained within the element's shadow
+ * root and thus cannot be used within an `<svg>` HTML element.
  */
 export const svg = tag(SVG_RESULT);