docs: update docs for pattern logic function

mmalerba · mmalerba · commit efecf1640f94 · 2025-08-07T14:47:46.000+09:00
diff --git a/packages/forms/experimental/src/api/validators/pattern.ts b/packages/forms/experimental/src/api/validators/pattern.ts
@@ -5,6 +5,7 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.dev/license
  */
+
 import {computed} from '@angular/core';
 import {aggregateProperty, property, validate} from '../logic';
 import {PATTERN} from '../property';
@@ -13,11 +14,16 @@ import {ValidationError} from '../validation_errors';
 import {BaseValidatorConfig} from './util';
 
 /**
- * Validator allowing to validate a string against a pattern.
+ * Binds a validator to the given path that requires the value to match a specific regex pattern.
+ * This function can only be called on string paths.
+ * In addition to binding a validator, this function adds `PATTERN` property to the field.
  *
- * @param path Path to the target field
- * @param pattern Regular expression to validate against.
- * @param config Optional, currently allows providing custom errors function.
+ * @param path Path of the field to validate
+ * @param pattern The RegExp pattern to match, or a LogicFn that returns the RegExp pattern.
+ * @param config Optional, allows providing any of the following options:
+ *  - `error`: Custom validation error(s) to be used instead of the default `ValidationError.pattern(pattern)`
+ *    or a function that receives the `FieldContext` and returns custom validation error(s).
+ * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
  */
 export function pattern<TPathKind extends PathKind = PathKind.Root>(
   path: FieldPath<string, TPathKind>,
@@ -31,7 +37,8 @@ export function pattern<TPathKind extends PathKind = PathKind.Root>(
   validate(path, (ctx) => {
     const pattern = ctx.state.property(PATTERN_MEMO)!();
 
-    // A pattern validator should not fail on an empty value.
+    // A pattern validator should not fail on an empty value. This matches the behavior of HTML's
+    // built in `pattern` attribute.
     if (pattern === undefined || ctx.value() == null || ctx.value() === '') {
       return undefined;
     }
