joyent/node — pull request #2633 by Benvie (2012-01-29 04:22:28+00:00)
Title: Add `NativeModule.prototype.deprecate` to formalize handling of deprecated core methods.

This following the functionality of `util._deprecationWarning` but provides it as a a function of NativeModule.prototype allowing simpler access from any core module. Additionally, it expands a bit on the functionality by doing the following:

* The deprecated method is replaced by a wrapper method that outputs the error/warning when first called without requiring it to be called from within the method.
* The method is set to non-enumerable. Deprecated/eventually to be removed interfaces have no business being visible.
* Upon first call, the wrapper outputs the warning and then sets sets the original function back as the value for that name. Thus there is zero overhead after the first call, not even a check to see if it has already been called.
* Provides a centralized and cleaner way to deprecate functionality in any core module that would be easy to expand/enrich in the future if there was a need.