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: https://github.com/nodejs/node/pull/3124
Ref: https://github.com/nodejs/node/issues/3122

PR-URL: https://github.com/nodejs/node/pull/3330
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Fedor Indutny <fedor@indutny.com>
Reviewed-By: Rod Vagg <rod@vagg.org>

diff --git a/doc/api/assert.markdown b/doc/api/assert.markdown
index fd1130e..7bf6ebb 100644 (file)
--- a/doc/api/assert.markdown
+++ b/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])