nodejs
diff --git a/‎doc/api/assert.markdown‎
Lines changed: 15 additions & 5 deletions b/‎doc/api/assert.markdown‎
Lines changed: 15 additions & 5 deletions
@@ -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])