docs: add missing documentation for error state properties (#23010)

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.

(cherry picked from commit 136fb5a)

Author: devversion

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;