Update match.js

lib/ext/match.js

@@ -18,8 +18,12 @@ module.exports = function(should, Assertion) {
    * If `other` is a regexp and given object is an object check values on matching regexp
    * If `other` is a function check if this function throws AssertionError on given object or return false - it will be assumed as not matched
    * If `other` is an object check if the same keys matched with above rules
-   * All other cases failed
-   *
+   * All other cases failed.
+   * 
+   * Usually it is right idea to add pre type assertions, like `.String()` or `.Object()` to be sure assertions will do what you are expecting.
+   * Object iteration happen by keys (properties with enumerable: true), thus some objects can cause small pain. Typical example is js 
+   * Error - it by default has 2 properties `name` and `message`, but they both non-enumerable. In this case make sure you specify checking props (see examples).
+   * 
    * @name match
    * @memberOf Assertion
    * @category assertion matching
@@ -48,6 +52,19 @@ module.exports = function(should, Assertion) {
    * .match({ '0': 10, '1': /c$/, '2': function(it) {
    *    return it.should.have.property('d', 10);
    * }});
+   * 
+   * var myString = 'abc';
+   * 
+   * myString.should.be.a.String().and.match(/abc/);
+   * 
+   * myString = {};
+   * 
+   * myString.should.match(/abc/); //yes this will pass
+   * //better to do
+   * myString.should.be.an.Object().and.not.empty().and.match(/abc/);//fixed
+   * 
+   * (new Error('boom')).should.match(/abc/);//passed because no keys
+   * (new Error('boom')).should.not.match({ message: /abc/ });//check specified property
    */
   Assertion.add('match', function(other, description) {
     this.params = {operator: 'to match ' + i(other), message: description};