Docs: Write assert.propContain() and notPropContains() pages

Also cross-link with propEqual pages, and improve those as well, in
particular to clarify that these too are recursive in regards to
nested objects being comparable using plain objects.

Ref qunitjs#1668.

docs/assert/notPropContains.md

@@ -0,0 +1,79 @@
+---
+layout: page-api
+title: assert.notPropContains()
+excerpt: Check that an object does not contain certain properties.
+groups:
+  - assert
+version_added: "unreleased"
+---
+
+`notPropContains( actual, expected, message = "" )`
+
+Check that an object does not contain certain properties.
+
+| name | description |
+|------|-------------|
+| `actual` | Expression being tested |
+| `expected` | Known comparison value |
+| `message` (string) | Short description of the actual value |
+
+
+The `notPropContains` assertion compares the subset of properties in the expected object, and tests that these keys are either absent or hold a value that is different according to a strict equality comparison.
+
+This method is recursive and allows partial comparison of nested objects as well.
+
+## See also
+
+* Use [`assert.propContain()`](./propContain.md) to test for the presence and equality of properties instead.
+
+## Examples
+
+```js
+QUnit.test( "example", assert => {
+
+  const result = {
+    foo: 0,
+    vehicle: {
+      timeCircuits: "on",
+      fluxCapacitor: "fluxing",
+      engine: "running"
+    },
+    quux: 1
+  };
+
+  // succeeds, property "timeCircuits" is actually "on"
+  assert.notPropContains( result, {
+    vehicle: {
+      timeCircuits: "off"
+    }
+  } );
+
+  // succeeds, property "wings" is not in the object
+  assert.notPropContains( result, {
+    vehicle: {
+      wings: "flapping"
+    }
+  } );
+
+  function Point( x, y ) {
+    this.x = x;
+    this.y = y;
+  }
+
+  assert.notPropContains(
+    new Point( 10, 20 ),
+    { z: 30 }
+  );
+
+  const nested = {
+    north: [ /* ... */ ],
+    east: new Point( 10, 20 ),
+    south: [ /* ... */ ],
+    west: [ /* ... */ ]
+  };
+
+  assert.notPropContains( nested, { east: new Point( 88, 42 ) } );
+  assert.notPropContains( nested, { east: { x: 88 } } );
+
+} );
+```

docs/assert/notPropEqual.md

@@ -1,7 +1,7 @@
 ---
 layout: page-api
 title: assert.notPropEqual()
-excerpt: A strict comparison of an object's own properties, checking for inequality.
+excerpt: Compare an object's own properties for inequality.
 groups:
   - assert
 redirect_from:
@@ -11,21 +11,22 @@ version_added: "1.11.0"
 
 `notPropEqual( actual, expected, message = "" )`
 
-A strict comparison of an object's own properties, checking for inequality.
+Compare an object's own properties using a strict inequality comparison.
 
 | name | description |
 |------|-------------|
 | `actual` | Expression being tested |
 | `expected` | Known comparison value |
 | `message` (string) | A short description of the assertion |
 
-The `notPropEqual` assertion uses the strict inverted comparison operator (`!==`) to compare the actual and expected arguments as Objects regarding only their properties but not their constructors.
+The `notPropEqual` assertion compares only an object's own properties, using the strict inquality operator (`!==`).
 
-When they aren't equal, the assertion passes; otherwise, it fails. When it fails, both actual and expected values are displayed in the test result, in addition to a given message.
+The test passes if there are properties with different values, or extra properties, or missing properties.
 
-[`assert.equal()`](./equal.md) can be used to test equality.
+## See also
 
-[`assert.propEqual()`](./propEqual.md) can be used to test strict equality of an Object properties.
+* Use [`assert.notPropContain()`](./notPropContain.md) to only check for the absence or inequality of some properties.
+* Use [`assert.propEqual()`](./propEqual.md) to test for equality of properties instead.
 
 ## Examples
 

docs/assert/propContain.md

@@ -0,0 +1,78 @@
+---
+layout: page-api
+title: assert.propContain()
+excerpt: Check that an object contains certain properties.
+groups:
+  - assert
+version_added: "unreleased"
+---
+
+`propContain( actual, expected, message = "" )`
+
+Check that an object contains certain properties.
+
+| name | description |
+|------|-------------|
+| `actual` | Expression being tested |
+| `expected` | Known comparison value |
+| `message` (string) | Short description of the actual value |
+
+
+The `propContain` assertion compares only the **subset** of properties in the expected object,
+and tests that these keys exist as own properties with strictly equal values.
+
+This method is recursive and allows partial comparison of nested objects as well.
+
+## See also
+
+* Use [`assert.propEqual()`](./propEqual.md) to compare all properties, considering extra properties as unexpected.
+* Use [`assert.notPropContain()`](./notPropContain.md) to test for the absence or inequality of certain properties.
+
+## Examples
+
+```js
+QUnit.test( "example", assert => {
+
+  const result = {
+    foo: 0,
+    vehicle: {
+      timeCircuits: "on",
+      fluxCapacitor: "fluxing",
+      engine: "running"
+    },
+    quux: 1
+  };
+
+  assert.propContains( result, {
+    foo: 0,
+    vehicle: { fluxCapacitor: "fluxing" }
+  } );
+
+  function Point( x, y ) {
+    this.x = x;
+    this.y = y;
+  }
+
+  assert.propContains(
+    new Point( 10, 20 ),
+    { y: 20 }
+  );
+
+  assert.propContains(
+    [ "a", "b" ],
+    { 1: "b" }
+  );
+
+  const nested = {
+    north: [ /* ... */ ],
+    east: new Point( 10, 20 ),
+    south: [ /* ... */ ],
+    west: [ /* ... */ ]
+  };
+
+  assert.propContains( nested, { east: new Point( 10, 20 ) } );
+  assert.propContains( nested, { east: { x: 10, y: 20 } } );
+  assert.propContains( nested, { east: { x: 10 } } );
+
+} );
+```

docs/assert/propEqual.md

@@ -1,7 +1,7 @@
 ---
 layout: page-api
 title: assert.propEqual()
-excerpt: A strict type and value comparison of an object's own properties.
+excerpt: Compare an object's own properties.
 groups:
   - assert
 redirect_from:
@@ -11,23 +11,28 @@ version_added: "1.11.0"
 
 `propEqual( actual, expected, message = "" )`
 
-A strict type and value comparison of an object's own properties.
+Compare an object's own properties using a strict comparison.
 
 | name | description |
 |------|-------------|
 | `actual` | Expression being tested |
 | `expected` | Known comparison value |
 | `message` (string) | A short description of the assertion |
 
-The `propEqual` assertion provides strictly (`===`) comparison of Object properties. Unlike [`assert.deepEqual()`](./deepEqual.md), this assertion can be used to compare two objects made with different constructors or prototypes.
+The `propEqual` assertion compares only an object's own properties. This means the expected value does not need to be an instance of the same class or otherwise inherit the same prototype, unlike with [`assert.deepEqual()`](./deepEqual.md).
 
-[`assert.strictEqual()`](./strictEqual.md) can be used to test strict equality.
+The assertion fails if values differ, if there are additional properties, or if some properties are missing.
 
-[`assert.notPropEqual()`](./notPropEqual.md) can be used to explicitly test strict inequality of Object properties.
+This method is recursive and can compare any nested or complex object via a plain object.
+
+## See also
+
+* Use [`assert.propContain()`](./propContain.md) to only check a subset of properties.
+* Use [`assert.notPropEqual()`](./notPropEqual.md) to test for the inequality of object properties instead.
 
 ## Examples
 
-Compare the properties values of two objects.
+Compare the property values of two objects.
 
 ```js
 QUnit.test( "example", assert => {
@@ -43,7 +48,7 @@ QUnit.test( "example", assert => {
   const foo = new Foo();
 
   // succeeds, own properties are strictly equal,
-  // and inherited properties (such as which object constructor) are ignored.
+  // and inherited properties (such as which constructor) are ignored.
   assert.propEqual( foo, {
     x: 1,
     y: 2