doc: add information about Assert behavior and maintenance

Assert is now locked. Userland alternatives should be used. Assert is
for testing Node.js itself.

Document potentially surprising use of enumerable properties only in
deep equality assertions.

Ref: #3124
Ref: #3122

PR-URL: #3330
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Fedor Indutny <[email protected]>
Reviewed-By: Rod Vagg <[email protected]>

Author: Trott

doc/api/assert.markdown

@@ -1,9 +1,10 @@
 # Assert
 
-    Stability: 2 - Stable
+    Stability: 3 - Locked
 
-This module is used for writing assertion tests. You can access it with
-`require('assert')`.
+This module is used so that Node.js can test itself. It can be accessed with
+`require('assert')`. However, it is recommended that a userland assertion
+library be used instead.
 
 ## assert.fail(actual, expected, message, operator)
 
@@ -26,8 +27,17 @@ Tests shallow, coercive inequality with the not equal comparison operator
 
 ## assert.deepEqual(actual, expected[, message])
 
-Tests for deep equality. Primitive values are compared with the equal comparison
-operator ( `==` ). Doesn't take object prototypes into account.
+Tests for deep equality. Primitive values are compared with the equal
+comparison operator ( `==` ).
+
+This only considers enumerable properties. It does not test object prototypes,
+attached symbols, or non-enumerable properties. This can lead to some
+potentially surprising results. For example, this does not throw an
+`AssertionError` because the properties on the `Error` object are
+non-enumerable:
+
+    // WARNING: This does not throw an AssertionError!
+    assert.deepEqual(Error('a'), Error('b'));
 
 ## assert.notDeepEqual(actual, expected[, message])