refactor(core): improve API documentation for model (angular#54925)

Improves the API documentation for `model`, similarly to how
we updated the `input` function.

PR Close angular#54925

packages/core/src/authoring/model/model.ts

@@ -31,72 +31,74 @@ export function modelRequiredFunction<T>(): ModelSignal<T> {
  * The function exposes an API for also declaring required models via the
  * `model.required` function.
  *
- * @usageNotes
- * Initialize a model in your directive or component by declaring a
- * class field and initializing it with the `model()` or `model.required()`
- * function.
- *
- * ```ts
- * @Directive({..})
- * export class MyDir {
- *   firstName = model<string>();            // string|undefined
- *   lastName = model.required<string>();    // string
- *   age = model(0);                         // number
- * }
- * ```
- *
  * @developerPreview
  */
 export interface ModelFunction {
   /**
-   * Initializes a model with an initial value. If no explicit value
-   * is specified, Angular will use `undefined`.
-   *
-   * Consider using `model.required` for models that don't need an
-   * initial value.
-   *
-   * @developerPreview
+   * Initializes a model of type `T` with an initial value of `undefined`.
+   * Angular will implicitly use `undefined` as initial value.
    */
   <T>(): ModelSignal<T|undefined>;
+  /** Initializes a model of type `T` with the given initial value. */
   <T>(initialValue: T, opts?: ModelOptions): ModelSignal<T>;
 
-  /**
-   * Initializes a required model.
-   *
-   * Users of your directive/component need to bind to the input side of the model.
-   * If unset, a compile time error will be reported.
-   *
-   * @developerPreview
-   */
-  required<T>(opts?: ModelOptions): ModelSignal<T>;
+  required: {
+    /**
+     * Initializes a required model.
+     *
+     * Users of your directive/component need to bind to the input side of the model.
+     * If unset, a compile time error will be reported.
+     */
+    <T>(opts?: ModelOptions): ModelSignal<T>;
+  };
 }
 
 /**
- * `model` declares a writeable signal that is exposed as an input/output pair on the containing
- * directive. The input name is taken either from the class member or from the `alias` option.
+ * `model` declares a writeable signal that is exposed as an input/output
+ * pair on the containing directive.
+ *
+ * The input name is taken either from the class member or from the `alias` option.
  * The output name is generated by taking the input name and appending `Change`.
  *
- * Initializes a model with an initial value. If no explicit value
- * is specified, Angular will use `undefined`.
+ * @usageNotes
  *
- * Consider using `model.required` for models that don't need an
- * initial value.
+ * To use `model()`, import the function from `@angular/core`.
  *
- * @usageNotes
- * Initialize a model in your directive or component by declaring a
- * class field and initializing it with the `model()` or `model.required()`
- * function.
+ * ```
+ * import {model} from '@angular/core`;
+ * ```
+ *
+ * Inside your component, introduce a new class member and initialize
+ * it with a call to `model` or `model.required`.
  *
  * ```ts
- * @Directive({..})
+ * @Directive({
+ *   ...
+ * })
  * export class MyDir {
- *   firstName = model<string>();            // string|undefined
- *   lastName = model.required<string>();    // string
- *   age = model(0);                         // number
+ *   firstName = model<string>();            // ModelSignal<string|undefined>
+ *   lastName  = model.required<string>();   // ModelSignal<string>
+ *   age       = model(0);                   // ModelSignal<number>
+ * }
+ * ```
+ *
+ * Inside your component template, you can display the value of a `model`
+ * by calling the signal.
+ *
+ * ```html
+ * <span>{{firstName()}}</span>
+ * ```
+ *
+ * Updating the `model` is equivalent to updating a writable signal.
+ *
+ * ```ts
+ * updateName(newFirstName: string): void {
+ *   this.firstName.set(newFirstName);
  * }
  * ```
  *
  * @developerPreview
+ * @initializerApiFunction
  */
 export const model: ModelFunction = (() => {
   // Note: This may be considered a side-effect, but nothing will depend on