doc: deprecate diagnostics_channel object subscribe method

PR-URL: #42714
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Chengzhong Wu <[email protected]>
Reviewed-By: Gerhard Stöbich <[email protected]>
Reviewed-By: Rafael Gonzaga <[email protected]>
Reviewed-By: Vladimir de Turckheim <[email protected]>

Author: Stephen Belanger

doc/api/deprecations.md

@@ -3137,6 +3137,24 @@ parameter in [`fs.write()`][], [`fs.writeFile()`][], [`fs.appendFile()`][],
 [`fs.writeFileSync()`][], and [`fs.appendFileSync()`][] is deprecated.
 Convert them to primitive strings.
 
+### DEP0163: `channel.subscribe(onMessage)`, `channel.unsubscribe(onMessage)`
+
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/42714
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+These methods were deprecated because they can be used in a way which does not
+hold the channel reference alive long enough to receive the events.
+
+Use [`diagnostics_channel.subscribe(name, onMessage)`][] or
+[`diagnostics_channel.unsubscribe(name, onMessage)`][] which does the same
+thing instead.
+
 [Legacy URL API]: url.md#legacy-url-api
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
@@ -3177,6 +3195,8 @@ Convert them to primitive strings.
 [`crypto.scrypt()`]: crypto.md#cryptoscryptpassword-salt-keylen-options-callback
 [`decipher.final()`]: crypto.md#decipherfinaloutputencoding
 [`decipher.setAuthTag()`]: crypto.md#deciphersetauthtagbuffer-encoding
+[`diagnostics_channel.subscribe(name, onMessage)`]: diagnostics_channel.md#diagnostics_channelsubscribename-onmessage
+[`diagnostics_channel.unsubscribe(name, onMessage)`]: diagnostics_channel.md#diagnostics_channelunsubscribename-onmessage
 [`dns.lookup()`]: dns.md#dnslookuphostname-options-callback
 [`dnsPromises.lookup()`]: dns.md#dnspromiseslookuphostname-options
 [`domain`]: domain.md

doc/api/diagnostics_channel.md

@@ -308,8 +308,11 @@ channel.publish({
 added:
  - v15.1.0
  - v14.17.0
+deprecated: REPLACEME
 -->
 
+> Stability: 0 - Deprecated: Use [`diagnostics_channel.subscribe(name, onMessage)`][]
+
 * `onMessage` {Function} The handler to receive channel messages
   * `message` {any} The message data
   * `name` {string|symbol} The name of the channel
@@ -344,6 +347,7 @@ channel.subscribe((message, name) => {
 added:
  - v15.1.0
  - v14.17.0
+deprecated: REPLACEME
 changes:
   - version:
     - v17.1.0
@@ -353,6 +357,8 @@ changes:
     description: Added return value. Added to channels without subscribers.
 -->
 
+> Stability: 0 - Deprecated: Use [`diagnostics_channel.unsubscribe(name, onMessage)`][]
+
 * `onMessage` {Function} The previous subscribed handler to remove
 * Returns: {boolean} `true` if the handler was found, `false` otherwise.
 
@@ -424,5 +430,6 @@ Emitted when server sends a response.
 
 [`'uncaughtException'`]: process.md#event-uncaughtexception
 [`channel.subscribe(onMessage)`]: #channelsubscribeonmessage
-[`diagnostics_channel.subscribe(name, onMessage)`]: #diagnostics_channelunsubscribename_onmessage
 [`diagnostics_channel.channel(name)`]: #diagnostics_channelchannelname
+[`diagnostics_channel.subscribe(name, onMessage)`]: #diagnostics_channelsubscribename-onmessage
+[`diagnostics_channel.unsubscribe(name, onMessage)`]: #diagnostics_channelunsubscribename-onmessage