Expand jsdocs for reactive-element and lit-element. (#2161)

Expand jsdocs for reactive-element and lit-element.
Added documentation for previously undocumented:

 * LitElement.connectedCallback()
 * LitElement.disconnectedCallback()
 * ReactiveElement.hasUpdated
 * ReactiveElement.addController
 * ReactiveElement.removeController

Co-authored-by: Andrew Jakubowicz <[email protected]>
Co-authored-by: Arthur Evans <[email protected]>

.changeset/great-walls-clap.md

@@ -0,0 +1,6 @@
+---
+'lit-element': patch
+'@lit/reactive-element': patch
+---
+
+Additional documentation on Lit APIs

packages/lit-element/src/lit-element.ts

@@ -137,6 +137,23 @@ export class LitElement extends ReactiveElement {
   }
 
   /**
+   * Invoked when the component is added to the document's DOM.
+   *
+   * In `connectedCallback()` you should setup tasks that should only occur when
+   * the element is connected to the document. The most common of these is
+   * adding event listeners to nodes external to the element, like a keydown
+   * event handler added to the window.
+   *
+   * ```ts
+   * connectedCallback() {
+   *   super.connectedCallback();
+   *   addEventListener('keydown', this._handleKeydown);
+   * }
+   * ```
+   *
+   * Typically, anything done in `connectedCallback()` should be undone when the
+   * element is disconnected, in `disconnectedCallback()`.
+   *
    * @category lifecycle
    */
   override connectedCallback() {
@@ -145,6 +162,22 @@ export class LitElement extends ReactiveElement {
   }
 
   /**
+   * Invoked when the component is removed from the document's DOM.
+   *
+   * This callback is the main signal to the element that it may no longer be
+   * used. `disconnectedCallback()` should ensure that nothing is holding a
+   * reference to the element (such as event listeners added to nodes external
+   * to the element), so that it is free to be garbage collected.
+   *
+   * ```ts
+   * disconnectedCallback() {
+   *   super.disconnectedCallback();
+   *   window.removeEventListener('keydown', this._handleKeydown);
+   * }
+   * ```
+   *
+   * An element may be re-connected after being disconnected.
+   *
    * @category lifecycle
    */
   override disconnectedCallback() {

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

@@ -759,11 +759,15 @@ export abstract class ReactiveElement
   private __updatePromise!: Promise<boolean>;
 
   /**
+   * True if there is a pending update as a result of calling `requestUpdate()`.
+   * Should only be read.
    * @category updates
    */
   isUpdatePending = false;
 
   /**
+   * Is set to `true` after the first update. The element code cannot assume
+   * that `renderRoot` exists before the element `hasUpdated`.
    * @category updates
    */
   hasUpdated = false;
@@ -817,6 +821,12 @@ export abstract class ReactiveElement
   }
 
   /**
+   * Registers a `ReactiveController` to participate in the element's reactive
+   * update cycle. The element automatically calls into any registered
+   * controllers during its lifecycle callbacks.
+   *
+   * If the element is connected when `addController()` is called, the
+   * controller's `hostConnected()` callback will be immediately called.
    * @category controllers
    */
   addController(controller: ReactiveController) {
@@ -831,6 +841,7 @@ export abstract class ReactiveElement
   }
 
   /**
+   * Removes a `ReactiveController` from the element.
    * @category controllers
    */
   removeController(controller: ReactiveController) {