is-shallow-equal: Documentation: Define shallow equality with inequality examples

[ntwb]

@aduth commented on Wed May 23 2018

Related Slack discussion: https://wordpress.slack.com/archives/C5UNMSU4R/p1526840808000021

@wordpress/is-shallow-equal includes the following text to describe its purpose:

A function for performing a shallow comparison between two objects or arrays. Two values have shallow equality when all of their members are strictly equal to the corresponding member of the other.

It's not entirely clear by this description the behavior that should be expected by the following example:

isShallowEqual( [ { id: 1 } ], [ { id: 1 } ] );

...except when the reader understands referential inequality of two newly-defined objects.

We should clarify in the documentation...

• The difference between shallow equality and deep equality
  • References to Lodash's deep _.isEqual as an alternative
• An example where @wordpress/is-shallow-equal may return false where a deep isEqual would return true (as above)
  • And unit test?

[aduth]

Considering this to be resolved by #13526