From b12e8d93fb4a45b1a16e37716ac6e0a684d5e220 Mon Sep 17 00:00:00 2001
From: Andrew Jakubowicz <spyr1014@gmail.com>
Date: Fri, 10 Jun 2022 15:26:35 -0700
Subject: [PATCH] [lit-html] Expand documentation for `TemplateResult` and
 `render`. (#2849)

---
 .changeset/eighty-windows-bow.md  |  6 +++++
 packages/lit-html/src/lit-html.ts | 37 +++++++++++++++++++++++++++----
 2 files changed, 39 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/eighty-windows-bow.md

diff --git a/.changeset/eighty-windows-bow.md b/.changeset/eighty-windows-bow.md
new file mode 100644
index 0000000000..254c29a4ac
--- /dev/null
+++ b/.changeset/eighty-windows-bow.md
@@ -0,0 +1,6 @@
+---
+'lit-html': patch
+'lit': patch
+---
+
+Expand documentation for `render` and `TemplateResult`.
diff --git a/packages/lit-html/src/lit-html.ts b/packages/lit-html/src/lit-html.ts
index 22cacf4542..4e16fcc835 100644
--- a/packages/lit-html/src/lit-html.ts
+++ b/packages/lit-html/src/lit-html.ts
@@ -443,7 +443,17 @@ const ELEMENT_PART = 6;
 const COMMENT_PART = 7;
 
 /**
- * The return type of the template tag functions.
+ * The return type of the template tag functions, {@linkcode html} and
+ * {@linkcode svg}.
+ *
+ * A `TemplateResult` object holds all the information about a template
+ * expression required to render it: the template strings, expression values,
+ * and type of template (html or svg).
+ *
+ * `TemplateResult` objects do not create any DOM on their own. To create or
+ * update DOM you need to render the `TemplateResult`. See
+ * [Rendering](https://lit.dev/docs/components/rendering) for more information.
+ *
  */
 export type TemplateResult<T extends ResultType = ResultType> = {
   // This property needs to remain unminified.
@@ -609,9 +619,28 @@ export interface RenderOptions {
 
 /**
  * Renders a value, usually a lit-html TemplateResult, to the container.
- * @param value
- * @param container
- * @param options
+ *
+ * This example renders the text "Hello, Zoe!" inside a paragraph tag, appending
+ * it to the container `document.body`.
+ *
+ * ```js
+ * import {html, render} from 'lit';
+ *
+ * const name = "Zoe";
+ * render(html`<p>Hello, ${name}!</p>`, document.body);
+ * ```
+ *
+ * @param value Any [renderable
+ *   value](https://lit.dev/docs/templates/expressions/#child-expressions),
+ *   typically a {@linkcode TemplateResult} created by evaluating a template tag
+ *   like {@linkcode html} or {@linkcode svg}.
+ * @param container A DOM container to render to. The first render will append
+ *   the rendered value to the container, and subsequent renders will
+ *   efficiently update the rendered value if the same result type was
+ *   previously rendered there.
+ * @param options See {@linkcode RenderOptions} for options documentation.
+ * @see
+ * {@link https://lit.dev/docs/libraries/standalone-templates/#rendering-lit-html-templates| Rendering Lit HTML Templates}
  */
 export const render = (
   value: unknown,