Fix mismatch createConnection and Socket.connect

net.createConnection() is wrapper for net.Socket.connect(),
but There is mismatch between them.

net.createConnection(port, [host])
net.Socket.connect(port, [host], [callback])

Fixes #1208.

doc/api/net.markdown

@@ -26,15 +26,17 @@ the socket is established the `'connect'` event will be emitted.
 
 The arguments for this method change the type of connection:
 
-* `net.createConnection(port, [host])`
+* `net.createConnection(port, [host], [callback])`
 
-  Creates a TCP connection to `port` on `host`. If `host` is omitted, `localhost`
+  Creates a TCP connection to `port` on `host`. If `host` is omitted,
-  will be assumed.
+  `localhost` will be assumed.
 
-* `net.createConnection(path)`
+* `net.createConnection(path, [callback])`
 
   Creates unix socket connection to `path`
 
+The `callback` parameter will be added as an listener for the 'connect` event.
+
 ---
 
 ### net.Server

lib/net_legacy.js

@@ -261,9 +261,9 @@ Socket.prototype.open = function(fd, type) {
 };
 
 
-exports.createConnection = function(port, host) {
+exports.createConnection = function(port, host, callback) {
   var s = new Socket();
-  s.connect(port, host);
+  s.connect(port, host, callback);
   return s;
 };
 

lib/net_uv.js

@@ -24,9 +24,9 @@ exports.createServer = function() {
 };
 
 
-exports.connect = exports.createConnection = function(port, host) {
+exports.connect = exports.createConnection = function(port, host /* [cb] */ ) {
   var s = new Socket();
-  s.connect(port, host);
+  s.connect(port, host, arguments[2]);
   return s;
 };
 
@@ -284,9 +284,13 @@ function afterWrite(status, handle, req, buffer) {
 }
 
 
-Socket.prototype.connect = function(port, host) {
+Socket.prototype.connect = function(port, host /* [cb] */) {
   var self = this;
 
+  if (typeof arguments[2] === 'function') {
+    self.on('connect', arguments[2]);
+  }
+
   timers.active(this);
 
   require('dns').lookup(host, function(err, ip, addressType) {

test/simple/test-net-create-connection.js

@@ -0,0 +1,42 @@
+// Copyright Joyent, Inc. and other Node contributors.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to permit
+// persons to whom the Software is furnished to do so, subject to the
+// following conditions:
+//
+// The above copyright notice and this permission notice shall be included
+// in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+// USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+var common = require('../common');
+var assert = require('assert');
+var net = require('net');
+
+var tcpPort = common.PORT;
+var connectHappened = false;
+
+var server = net.createServer(function(socket) {
+  server.close();
+  socket.end();
+});
+server.listen(tcpPort, 'localhost', function() {
+  var client = net.createConnection(tcpPort, 'localhost', function() {
+    connectHappened = true;
+  });
+});
+
+process.on('exit', function () {
+  assert.ok(connectHappened);
+});
+