domain: add soft deprecation notice

Per the TC meeting on 2014-12-10, domains will be "soft deprecated"
until a suitable replacement API is available; at which time they
will be fully deprecated. Full deprecation will include references
to replacement API and the application of util.deprecate to the domain
api.

PR-URL: nodejs#141
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Ben Noordhuis <[email protected]>

doc/api/domain.markdown

@@ -2,6 +2,13 @@
 
     Stability: 2 - Unstable
 
+**This module is pending deprecation**. Once a replacement API has been
+finalized, this module will be fully deprecated. Most end users should
+**not** have cause to use this module. Users who absolutely must have
+the functionality that domains provide may rely on it for the time being
+but should expect to have to migrate to a different solution
+in the future.
+
 Domains provide a way to handle multiple different IO operations as a
 single group.  If any of the event emitters or callbacks registered to a
 domain emit an `error` event, or throw an error, then the domain object

lib/domain.js

@@ -21,6 +21,11 @@
 
 'use strict';
 
+// WARNING: THIS MODULE IS PENDING DEPRECATION.
+//
+// No new pull requests targeting this module will be accepted
+// unless they address existing, critical bugs.
+
 var util = require('util');
 var EventEmitter = require('events');
 var inherits = util.inherits;