docs: update OnChanges API reference w/ signal input

jelbourn · thePunderWoman · commit 871fa1b2ddf1 · 2026-01-13T09:04:24.000-08:00
We had some reports of LLMs claiming that `ngOnChanges` does not include
changes for signal-based inputs. This is wrong (and the LLMs just made
it up), but we can update the docs at least to demonstrate `ngOnChanges`
with signal-based inputs.

Previously, the API reference used a real test as a code example, but
updating the test to a signal-based input is more involved than this
change needs to call for.
diff --git a/packages/core/src/change_detection/lifecycle_hooks.ts b/packages/core/src/change_detection/lifecycle_hooks.ts
@@ -9,7 +9,8 @@ import {SimpleChanges} from './simple_change';
 
 /**
  * @description
- * A lifecycle hook that is called when any data-bound property of a directive changes.
+ * A lifecycle hook that is called when the value of one or more component or directive inputs
+ * change. This includes both signal-based and decorator-based inputs.
  * Define an `ngOnChanges()` method to handle the changes.
  *
  * @see {@link DoCheck}
@@ -18,9 +19,19 @@ import {SimpleChanges} from './simple_change';
  *
  * @usageNotes
  * The following snippet shows how a component can implement this interface to
- * define an on-changes handler for an input property.
- *
- * {@example core/ts/metadata/lifecycle_hooks_spec.ts region='OnChanges'}
+ * define an on-changes handler for an input property. While you should prefer
+ * `computed` and `effect` when working with signal-based inputs, the `ngOnChanges`
+ * method does include value changes for signal-based inputs.
+ *
+ * ```ts
+ * @Component({ ... })
+ * export class UserProfile implements OnChanges {
+ *   userId = input<number>(0);
+ *   ngOnChanges(changes: SimpleChanges<UserProfile>) {
+ *     // changes.userId contains the old and new value.
+ *   }
+ * }
+ * ```
  *
  * @publicApi
  */
