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

.changeset/eighty-windows-bow.md

@@ -0,0 +1,6 @@
+---
+'lit-html': patch
+'lit': patch
+---
+
+Expand documentation for `render` and `TemplateResult`.

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}.
+ *
+ * The `TemplateResult` object captures the arguments passed into the tag
+ * function. A special array of strings that retain their identity between
+ * multiple evaluations of the tagged literal, and the values from the
+ * interpolated expressions.
+ *
+ * To create or update DOM from the `TemplateResult` 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,24 @@ export interface RenderOptions {
 
 /**
  * Renders a value, usually a lit-html TemplateResult, to the container.
- * @param value
- * @param container
- * @param options
+ *
+ * For example, to render "Hello, Zoe!" 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, 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.
  */
 export const render = (
   value: unknown,