[reactive-element] Expand JSDocs, and code sample syntax fixes (#2457)

Documentation added to `willUpdate` lifecycle callback.
Code examples and doc additions to `firstUpdated` and `attributeChangedCallback`.

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

.changeset/sweet-emus-run.md

@@ -0,0 +1,6 @@
+---
+'@lit/reactive-element': patch
+'lit': patch
+---
+
+Add JSDoc to the `willUpdate` lifecycle callback. Expand the docs for `firstUpdated`, and `attributeChangedCallback`. Minor code sample fixes.

packages/reactive-element/src/decorators/event-options.ts

@@ -30,7 +30,7 @@ import {decorateProperty} from './base.js';
  *
  *   render() {
  *     return html`
- *       <div @click=${this._onClick}`>
+ *       <div @click=${this._onClick}>
  *         <button></button>
  *       </div>
  *     `;

packages/reactive-element/src/decorators/query-assigned-elements.ts

@@ -48,7 +48,7 @@ export interface QueryAssignedElementsOptions
  * A property decorator that converts a class property into a getter that
  * returns the `assignedElements` of the given `slot`. Provides a declarative
  * way to use
- * [`slot.assignedElements`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedElements).
+ * [`HTMLSlotElement.assignedElements`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedElements).
  *
  * Can be passed an optional {@linkcode QueryAssignedElementsOptions} object.
  *

packages/reactive-element/src/decorators/query-assigned-nodes.ts

@@ -79,7 +79,8 @@ export function queryAssignedNodes(
  *
  * Note the type of this property should be annotated as `Array<Node>` if used
  * without a `selector` or `Array<HTMLElement>` if a selector is provided.
- * Please use `@queryAssignedElements` if using a CSS selector is desired.
+ * Use {@linkcode queryAssignedElements @queryAssignedElements} to list only
+ * elements, and optionally filter the element list using a CSS selector.
  *
  * @param slotName A string name of the slot.
  * @param flatten A boolean which when true flattens the assigned nodes,

packages/reactive-element/src/reactive-element.ts

@@ -334,10 +334,10 @@ export abstract class ReactiveElement
    *
    * ```ts
    * // Enable for all ReactiveElement subclasses
-   * ReactiveElement.enableWarning.?('migration');
+   * ReactiveElement.enableWarning?.('migration');
    *
    * // Enable for only MyElement and subclasses
-   * MyElement.enableWarning.?('migration');
+   * MyElement.enableWarning?.('migration');
    * ```
    *
    * @nocollapse
@@ -353,10 +353,10 @@ export abstract class ReactiveElement
    *
    * ```ts
    * // Disable for all ReactiveElement subclasses
-   * ReactiveElement.disableWarning.?('migration');
+   * ReactiveElement.disableWarning?.('migration');
    *
    * // Disable for only MyElement and subclasses
-   * MyElement.disableWarning.?('migration');
+   * MyElement.disableWarning?.('migration');
    * ```
    *
    * @nocollapse
@@ -964,6 +964,14 @@ export abstract class ReactiveElement
 
   /**
    * Synchronizes property values when attributes change.
+   *
+   * Specifically, when an attribute is set, the corresponding property is set.
+   * You should rarely need to implement this callback. If this method is
+   * overridden, `super.attributeChangedCallback(name, _old, value)` must be
+   * called.
+   *
+   * See [using the lifecycle callbacks](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#using_the_lifecycle_callbacks)
+   * on MDN for more information about the `attributeChangedCallback`.
    * @category attributes
    */
   attributeChangedCallback(
@@ -1232,6 +1240,24 @@ export abstract class ReactiveElement
   }
 
   /**
+   * Invoked before `update()` to compute values needed during the update.
+   *
+   * Implement `willUpdate` to compute property values that depend on other
+   * properties and are used in the rest of the update process.
+   *
+   * ```ts
+   * willUpdate(changedProperties) {
+   *   // only need to check changed properties for an expensive computation.
+   *   if (changedProperties.has('firstName') || changedProperties.has('lastName')) {
+   *     this.sha = computeSHA(`${this.firstName} ${this.lastName}`);
+   *   }
+   * }
+   *
+   * render() {
+   *   return html`SHA: ${this.sha}`;
+   * }
+   * ```
+   *
    * @category updates
    */
   protected willUpdate(_changedProperties: PropertyValues): void {}
@@ -1364,6 +1390,12 @@ export abstract class ReactiveElement
    * Invoked when the element is first updated. Implement to perform one time
    * work on the element after update.
    *
+   * ```ts
+   * firstUpdated() {
+   *   this.renderRoot.getElementById('my-text-area').focus();
+   * }
+   * ```
+   *
    * Setting properties inside this method will trigger the element to update
    * again after this update cycle completes.
    *