Inconsistent documentation/implementation of "forEachIdentityChange" in change_detection/differs.

📚 Docs or angular.io bug report

Description

Inconsistent documentation of forEachIdentityChange in IterableChanges vs implementation in DefaultIterableDiffer.

Documentation states: Iterate over all items which had their identity (as computed by the `TrackByFunction`) changed.

Implementation compares identity of the items, not the return of trackByFunction: if (!looseIdentical(record.item, item)) this._addIdentityChange(record, item);

🔬 Minimal Reproduction

What’s the affected URL?**

git repo: angular/packages/core/src/change_detection/differs/

Reproduction Steps**

Not applicable.

Expected vs Actual Behavior**

Either documentation or implementation should be changed to be consistent.

📷Screenshot

Not applicable.

🔥 Exception or Error

Not applicable.

🌍 Your Environment

Angular 9.1.x - 10.x.x (but I think this exists since 4.0.0)

Browser info

Not applicable.

Anything else relevant?

Nope.

[3Shain]

I think naming it forEachItemChange would be better.

Because at first I recognised this as “the items that identity changed (and the identity is computed by trackBy)”, but when an identity indeed changed it was actually performed by an addition and a removal. I don’t think the current one make sense.

[3Shain]

What does ‘identity’ mean here?

I have following codes:

// assume there is a differ object, with trackBy fn : (index,identity)=>identity.id
const array = [{ id: 1 }, { id: 2 }, { id: 3 }]
differ.diff(array);

differ.diff([array[0],array[1],{ id:3 }]) 
// for this `forEachIdentityChange` still gives the third item
// but if this does really depend on trackBy then I expect no changes here.