docs: clarify ngDoCheck invocation behavior with OnPush strategy

The previous documentation for `DoCheck` / `ngDoCheck` implied that the
default change-detector had run on the directive itself, which is
misleading. `ngDoCheck` is actually invoked when the *parent's*
change-detector checks the directive's input bindings — meaning it fires
even for `OnPush` components whose own change detection was skipped.

Updated three places in lifecycle_hooks.ts:
- Interface description: scopes "the check" to input bindings in the
  parent template and adds an explicit OnPush callout.
- "detects changes" clarified to "detects changes to the directive's
  input bindings".
- Method description: "after the default change-detector runs" →
  "after the default change-detector has checked the directive's input
  bindings in the parent template".

Fixes #48140

(cherry picked from commit ca44055166)
This commit is contained in:
arturovt 2026-05-20 20:56:03 +03:00 committed by leonsenft
parent 51571e3652
commit 7f1cfcbc97

View file

@ -76,14 +76,19 @@ export interface OnInit {
/**
* A lifecycle hook that invokes a custom change-detection function for a directive,
* in addition to the check performed by the default change-detector.
* in addition to the check performed by the default change-detector on the input
* bindings for this directive usage in the parent template. Note that this hook is
* invoked even when the directive's own change detection is skipped (e.g., with
* the `OnPush` change detection strategy). Developers might use this hook to
* implement a custom change detection strategy for some of the inputs.
*
* The default change-detection algorithm looks for differences by comparing
* bound-property values by reference across change detection runs. You can use this
* hook to check for and respond to changes by some other means.
*
* When the default change detector detects changes, it invokes `ngOnChanges()` if supplied,
* regardless of whether you perform additional change detection.
* When the default change detector detects changes to the directive's input bindings,
* it invokes `ngOnChanges()` if supplied, regardless of whether you perform
* additional change detection.
* Typically, you should not use both `DoCheck` and `OnChanges` to respond to
* changes on the same input.
*
@ -104,7 +109,8 @@ export interface OnInit {
export interface DoCheck {
/**
* A callback method that performs change-detection, invoked
* after the default change-detector runs.
* after the default change-detector has checked the directive's input
* bindings in the parent template.
* See `KeyValueDiffers` and `IterableDiffers` for implementing
* custom change checking for collections.
*