doc: Add notes for using @@toStringTag

[yosuke-furukawa]

I checked util.is* functions. the following functions may be broken using ES2015 features.

• util.isDate
• util.isError
• util.isRegExp

those functions use Object.prototype.toString.call to check the type.
But @@toStringTag can chage the returned value. @@toStringTag is enabled under --harmony on io.js v2.

For example,

var fakeRegExp = {}; 
fakeRegExp[Symbol.toStringTag] = 'RegExp';
console.log(fakeRegExp.toString()); // [object RegExp]
console.log(util.isRegExp(obj)); // true

var regexp = /a/;
console.log(util.isRegExp(regexp)); // true
RegExp.prototype[Symbol.toStringTag] = 'Array';
console.log(util.isRegExp(regexp)); // false

This PR is to add a notice in these util function.

[Fishrock123]

@yosuke-furukawa would you mind changing this to inform about this, but also center it around deprecation notices? That would be great, it's something I never got around to doing. :)

Prior discussion: #1301

[yosuke-furukawa]

@Fishrock123 +1. We would be better to deprecate util.is* functions in v3. And we will add these notice to deprecation reason.

[Fishrock123]

@yosuke-furukawa I wouldn't delay a deprecation notice in the docs for v3 (It was supposed to be in v2 so..)

Besides, we'll probably need to wait a good while before we deprecate this with a run-time warning.

[jasnell]

@Fishrock123 @yosuke-furukawa ... is there reason to keep this one open? Is it still needed? If so, it needs to be updated.

[bnoordhuis]

"Note:" (capitalize) and please wrap lines at 80 columns. I'd write 'enabled with' instead of 'enabled under'.

[bnoordhuis]

LGTM when rebased and comments addressed. I think this is a valuable addition to the documentation.

[jasnell]

@yosuke-furukawa ... could I ask you to please rebase, update and address @bnoordhuis' comments. Thank you!

[Trott]

This can be closed, I think. I think the problem this warns about has been corrected. The sample code for getting incorrect results seems to now return the correct results. It may have been fixed in 6526ae7.

/cc @cjihrig

If there's something I'm missing, please feel free to re-open.

[cjihrig]

This is mostly resolved. The isError() function still relies on Object.prototype.toString().