From 76bf3ddee7f1714c924e648b2aaad0e36222d9b5 Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Fri, 1 May 2020 23:38:34 +0200
Subject: [PATCH] doc: deprecate socket.connect

`socket.connect` is subtly broken due to timing and
_undestroy issues. Discourage usage and ask users
to instead create a new socket instance.

Refs: https://github.com/nodejs/node/pull/33203
---
 doc/api/deprecations.md | 18 ++++++++++++++++++
 doc/api/net.md          |  5 +++++
 2 files changed, 23 insertions(+)

diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index 7ff8503f695aa0..a34644703a7496 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -2668,6 +2668,22 @@ Type: Documentation-only
 
 Use [`request.destroy()`][] instead of [`request.abort()`][].
 
+<a id="DEP0XXX"></a>
+### DEP0XXX: Use `net.connect()` instead of re-using sockets through
+`socket.connect()`
+<!-- YAML
+changes:
+  - version:
+    - REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/33204
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+Use [`net.connect()`][] instead of re-using sockets through
+[`socket.connect()`][].
+
 [`--pending-deprecation`]: cli.html#cli_pending_deprecation
 [`--throw-deprecation`]: cli.html#cli_throw_deprecation
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
@@ -2722,6 +2738,7 @@ Use [`request.destroy()`][] instead of [`request.abort()`][].
 [`https.get()`]: https.html#https_https_get_options_callback
 [`https.request()`]: https.html#https_https_request_options_callback
 [`module.createRequire()`]: modules.html#modules_module_createrequire_filename
+[`net.connect()`]: net.html#net_net_connect
 [`os.networkInterfaces()`]: os.html#os_os_networkinterfaces
 [`os.tmpdir()`]: os.html#os_os_tmpdir
 [`process.env`]: process.html#process_process_env
@@ -2742,6 +2759,7 @@ Use [`request.destroy()`][] instead of [`request.abort()`][].
 [`script.createCachedData()`]: vm.html#vm_script_createcacheddata
 [`setInterval()`]: timers.html#timers_setinterval_callback_delay_args
 [`setTimeout()`]: timers.html#timers_settimeout_callback_delay_args
+[`socket.connect()`]: net.html#net_socket_connect
 [`timeout.ref()`]: timers.html#timers_timeout_ref
 [`timeout.refresh()`]: timers.html#timers_timeout_refresh
 [`timeout.unref()`]: timers.html#timers_timeout_unref
diff --git a/doc/api/net.md b/doc/api/net.md
index 28842d0abe9b90..6073308d15424e 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -581,6 +581,11 @@ added: v0.5.3
 The amount of bytes sent.
 
 ### `socket.connect()`
+<!-- YAML
+deprecated: REPLACEME
+-->
+
+> Stability: 0 - Deprecated: Use [`net.connect()`][] instead.
 
 Initiate a connection on a given socket.