From 24d420a8eaeccdf668768212015d36e921e58359 Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Mon, 13 Apr 2020 13:41:29 +0200
Subject: [PATCH 1/7] doc: improve net docs

Refer back to streams docs for further and more accurate
description of behavior details.

Refs: https://github.com/nodejs/node/issues/31916
---
 doc/api/net.md | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/doc/api/net.md b/doc/api/net.md
index a9d84e0b174882..4d1f80b3bab9e9 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -722,25 +722,26 @@ that the
 [`socket.connect(options[, connectListener])`][`socket.connect(options)`]
 callback is a listener for the `'connect'` event.
 
-### `socket.destroy([exception])`
+### `socket.destroy([error])`
 <!-- YAML
 added: v0.1.90
 -->
 
-* `exception` {Object}
+* `error` {Object}
 * Returns: {net.Socket}
 
-Ensures that no more I/O activity happens on this socket. Only necessary in
-case of errors (parse error or so).
+Ensures that no more I/O activity happens on this socket. Effectivly discards
+any buffered data and ends the socket.
 
-If `exception` is specified, an [`'error'`][] event will be emitted and any
-listeners for that event will receive `exception` as an argument.
+See, [`writable.destroy()`][] for further details.
 
 ### `socket.destroyed`
 
 * {boolean} Indicates if the connection is destroyed or not. Once a
   connection is destroyed no further data can be transferred using it.
 
+See, [`writable.destroyed`][] for further details.
+
 ### `socket.end([data[, encoding]][, callback])`
 <!-- YAML
 added: v0.1.90
@@ -754,8 +755,7 @@ added: v0.1.90
 Half-closes the socket. i.e., it sends a FIN packet. It is possible the
 server will still send some data.
 
-If `data` is specified, it is equivalent to calling
-`socket.write(data, encoding)` followed by [`socket.end()`][].
+See, [`writable.end()`][] for further details.
 
 ### `socket.localAddress`
 <!-- YAML
@@ -1268,6 +1268,9 @@ Returns `true` if input is a version 6 IP address, otherwise returns `false`.
 [`socket.setEncoding()`]: #net_socket_setencoding_encoding
 [`socket.setTimeout()`]: #net_socket_settimeout_timeout_callback
 [`socket.setTimeout(timeout)`]: #net_socket_settimeout_timeout_callback
+[`writable.destroyed`]: stream.html#stream_writable_destroyed
+[`writable.destroy()`]: stream.html#stream_writable_destroy_error
+[`writable.end()`]: stream.html#stream_writable_end_chunk_encoding_callback
 [half-closed]: https://tools.ietf.org/html/rfc1122
 [stream_writable_write]: stream.html#stream_writable_write_chunk_encoding_callback
 [unspecified IPv4 address]: https://en.wikipedia.org/wiki/0.0.0.0

From a3715afbcfcb39e5832a5e54390e8765c4653c8b Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Mon, 13 Apr 2020 13:59:20 +0200
Subject: [PATCH 2/7] Apply suggestions from code review

Co-Authored-By: mscdex <mscdex@users.noreply.github.com>
---
 doc/api/net.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/api/net.md b/doc/api/net.md
index 4d1f80b3bab9e9..e592e24fddaaa1 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -730,7 +730,7 @@ added: v0.1.90
 * `error` {Object}
 * Returns: {net.Socket}
 
-Ensures that no more I/O activity happens on this socket. Effectivly discards
+Ensures that no more I/O activity happens on this socket. It effectively discards
 any buffered data and ends the socket.
 
 See, [`writable.destroy()`][] for further details.
@@ -740,7 +740,7 @@ See, [`writable.destroy()`][] for further details.
 * {boolean} Indicates if the connection is destroyed or not. Once a
   connection is destroyed no further data can be transferred using it.
 
-See, [`writable.destroyed`][] for further details.
+See [`writable.destroyed`][] for further details.
 
 ### `socket.end([data[, encoding]][, callback])`
 <!-- YAML
@@ -755,7 +755,7 @@ added: v0.1.90
 Half-closes the socket. i.e., it sends a FIN packet. It is possible the
 server will still send some data.
 
-See, [`writable.end()`][] for further details.
+See [`writable.end()`][] for further details.
 
 ### `socket.localAddress`
 <!-- YAML

From f14c446e32bc43df0ce12e92b3b4ff0fccab4b40 Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Mon, 13 Apr 2020 15:14:18 +0200
Subject: [PATCH 3/7] fixup: fix link

---
 doc/api/net.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/net.md b/doc/api/net.md
index e592e24fddaaa1..daba4dddf0e5f7 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -1261,7 +1261,7 @@ Returns `true` if input is a version 6 IP address, otherwise returns `false`.
 [`socket.connect(path)`]: #net_socket_connect_path_connectlistener
 [`socket.connect(port)`]: #net_socket_connect_port_host_connectlistener
 [`socket.connecting`]: #net_socket_connecting
-[`socket.destroy()`]: #net_socket_destroy_exception
+[`socket.destroy()`]: #net_socket_destroy_error
 [`socket.end()`]: #net_socket_end_data_encoding_callback
 [`socket.pause()`]: #net_socket_pause
 [`socket.resume()`]: #net_socket_resume

From f63e0c9ac6c9a34cad408f2330071fc93bf56895 Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Mon, 13 Apr 2020 15:28:29 +0200
Subject: [PATCH 4/7] fixup: remove misleading comment

---
 doc/api/net.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/doc/api/net.md b/doc/api/net.md
index daba4dddf0e5f7..6c7869d5154a5a 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -730,8 +730,7 @@ added: v0.1.90
 * `error` {Object}
 * Returns: {net.Socket}
 
-Ensures that no more I/O activity happens on this socket. It effectively discards
-any buffered data and ends the socket.
+Ensures that no more I/O activity happens on this socket.
 
 See, [`writable.destroy()`][] for further details.
 

From b70cdcfe5199c07d7d6130bba6c779c60a54993b Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Mon, 13 Apr 2020 19:56:08 +0200
Subject: [PATCH 5/7] fixup: add note regarding TCP rst

---
 doc/api/net.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/api/net.md b/doc/api/net.md
index 6c7869d5154a5a..0375190a5b8d2e 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -730,7 +730,8 @@ added: v0.1.90
 * `error` {Object}
 * Returns: {net.Socket}
 
-Ensures that no more I/O activity happens on this socket.
+Ensures that no more I/O activity happens on this socket. This destroys
+the stream but does not explicitly cause a TCP stream reset (RST).
 
 See, [`writable.destroy()`][] for further details.
 

From c7837ad071c8178e66518dca0d8751692c9fc68b Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Mon, 13 Apr 2020 21:03:37 +0200
Subject: [PATCH 6/7] fixup: apply suggestion

---
 doc/api/net.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/api/net.md b/doc/api/net.md
index 0375190a5b8d2e..7ab3e2ab7e8470 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -730,8 +730,8 @@ added: v0.1.90
 * `error` {Object}
 * Returns: {net.Socket}
 
-Ensures that no more I/O activity happens on this socket. This destroys
-the stream but does not explicitly cause a TCP stream reset (RST).
+Ensures that no more I/O activity happens on this socket.
+Destroys the stream and closes the connection.
 
 See, [`writable.destroy()`][] for further details.
 

From 90479052c53a581c8e4cf36eb8c8af5d615b531c Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Mon, 13 Apr 2020 21:21:26 +0200
Subject: [PATCH 7/7] Update doc/api/net.md

Co-Authored-By: mscdex <mscdex@users.noreply.github.com>
---
 doc/api/net.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/net.md b/doc/api/net.md
index 7ab3e2ab7e8470..aa2b918ecdac12 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -733,7 +733,7 @@ added: v0.1.90
 Ensures that no more I/O activity happens on this socket.
 Destroys the stream and closes the connection.
 
-See, [`writable.destroy()`][] for further details.
+See [`writable.destroy()`][] for further details.
 
 ### `socket.destroyed`