From c20f6cf483143c213e9b95d264673354f24e5d9f Mon Sep 17 00:00:00 2001
From: Paul Gschwendtner <paulgschwendtner@gmail.com>
Date: Thu, 3 Jun 2021 21:06:15 +0200
Subject: [PATCH] docs: add missing documentation for error state properties

All components relying on the `mixinErrorState` currently lack
descriptions for the mixin-defined properties. This commit adds
JSDoc descriptions for these properties. Also adds a small internal
note about why `stateChanges` is declared as part of the mixin.
---
 .../core/common-behaviors/error-state.ts      | 21 ++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/src/material/core/common-behaviors/error-state.ts b/src/material/core/common-behaviors/error-state.ts
index 2953648d832c..2289fdfdb444 100644
--- a/src/material/core/common-behaviors/error-state.ts
+++ b/src/material/core/common-behaviors/error-state.ts
@@ -14,9 +14,13 @@ import {AbstractConstructor, Constructor} from './constructor';
 
 /** @docs-private */
 export interface CanUpdateErrorState {
-  updateErrorState(): void;
+  /** Emits whenever the component state changes. */
   readonly stateChanges: Subject<void>;
+  /** Updates the error state based on the provided error state matcher. */
+  updateErrorState(): void;
+  /** Whether the component is in an error state. */
   errorState: boolean;
+  /** An object used to control the error state of the component. */
   errorStateMatcher: ErrorStateMatcher;
 }
 
@@ -45,17 +49,20 @@ export function mixinErrorState<T extends AbstractConstructor<HasErrorState>>(ba
 export function mixinErrorState<T extends Constructor<HasErrorState>>(base: T):
   CanUpdateErrorStateCtor & T {
   return class extends base {
+    // This class member exists as an interop with `MatFormFieldControl` which expects
+    // a public `stateChanges` observable to emit whenever the form field should be updated.
+    // The description is not specifically mentioning the error state, as classes using this
+    // mixin can/should emit an event in other cases too.
+    /** Emits whenever the component state changes. */
+    readonly stateChanges = new Subject<void>();
+
     /** Whether the component is in an error state. */
     errorState: boolean = false;
 
-    /**
-     * Stream that emits whenever the state of the input changes such that the wrapping
-     * `MatFormField` needs to run change detection.
-     */
-    readonly stateChanges = new Subject<void>();
-
+    /** An object used to control the error state of the component. */
     errorStateMatcher: ErrorStateMatcher;
 
+    /** Updates the error state based on the provided error state matcher. */
     updateErrorState() {
       const oldState = this.errorState;
       const parent = this._parentFormGroup || this._parentForm;