net: doc deprecate bufferSize

PR-URL: #34088
Refs: #34078
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

doc/api/deprecations.md

@@ -2707,6 +2707,19 @@ Type: Runtime
 `Transform._transformState` will be removed in future versions where it is
 no longer required due to simplification of the implementation.
 
+<a id="DEP0XXX"></a>
+### DEP0XXX: `socket.bufferSize`
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/REPLACEME
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+[`socket.bufferSize`][] is just an alias for [`writable.writableLength`][].
+
 [`--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
@@ -2781,6 +2794,7 @@ no longer required due to simplification of the implementation.
 [`script.createCachedData()`]: vm.html#vm_script_createcacheddata
 [`setInterval()`]: timers.html#timers_setinterval_callback_delay_args
 [`setTimeout()`]: timers.html#timers_settimeout_callback_delay_args
+[`socket.bufferSize`]: net.html#net_socket_buffersize
 [`timeout.ref()`]: timers.html#timers_timeout_ref
 [`timeout.refresh()`]: timers.html#timers_timeout_refresh
 [`timeout.unref()`]: timers.html#timers_timeout_unref
@@ -2817,6 +2831,7 @@ no longer required due to simplification of the implementation.
 [`util`]: util.html
 [`worker.exitedAfterDisconnect`]: cluster.html#cluster_worker_exitedafterdisconnect
 [`worker.terminate()`]: worker_threads.html#worker_threads_worker_terminate
+[`writable.writableLength`]: stream.html#stream_writable_writablelength
 [`zlib.bytesWritten`]: zlib.html#zlib_zlib_byteswritten
 [Legacy URL API]: url.html#url_legacy_url_api
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf

doc/api/net.md

@@ -545,8 +545,12 @@ socket as reported by the operating system:
 ### `socket.bufferSize`
 <!-- YAML
 added: v0.3.8
+deprecated:
+  - REPLACEME
 -->
 
+> Stability: 0 - Deprecated: Use [`writable.writableLength`][] instead.
+
 * {integer}
 
 This property shows the number of characters buffered for writing. The buffer
@@ -1276,6 +1280,7 @@ 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.writableLength`]: stream.html#stream_writable_writablelength
 [`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