From 7777f22a709f002da835370af99df01d8651b370 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Mon, 31 Jan 2022 00:34:29 +0100
Subject: [PATCH] doc: deprecate `crypto.getRandomValues` alias

Refs: https://github.com/nodejs/node/pull/41760
---
 doc/api/crypto.md       |  5 +++--
 doc/api/deprecations.md | 16 ++++++++++++++++
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 4b1a54326295c7..3f7387c2044108 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -4107,13 +4107,14 @@ console.log(getHashes()); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]
 
 <!-- YAML
 added: v17.4.0
+deprecated: REPLACEME
 -->
 
+> Stability: 0 - Deprecated. Use [`crypto.webcrypto.getRandomValues()`][] instead.
+
 * `typedArray` {Buffer|TypedArray|DataView|ArrayBuffer}
 * Returns: {Buffer|TypedArray|DataView|ArrayBuffer} Returns `typedArray`.
 
-A convenient alias for [`crypto.webcrypto.getRandomValues()`][].
-
 ### `crypto.hkdf(digest, ikm, salt, info, keylen, callback)`
 
 <!-- YAML
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index 4cb8606c1f6615..06679fbdf8791d 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -3056,6 +3056,21 @@ This method was deprecated because it is not compatible with
 
 Use [`buffer.subarray`][] which does the same thing instead.
 
+### DEP0159: `require('node:crypto').getRandomValues()`
+
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/41596
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+This method was deprecated because it is is relying on a non-standard behavior.
+
+Use [`crypto.webcrypto.getRandomValues()`][] 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
@@ -3094,6 +3109,7 @@ Use [`buffer.subarray`][] which does the same thing instead.
 [`crypto.pbkdf2()`]: crypto.md#cryptopbkdf2password-salt-iterations-keylen-digest-callback
 [`crypto.randomBytes()`]: crypto.md#cryptorandombytessize-callback
 [`crypto.scrypt()`]: crypto.md#cryptoscryptpassword-salt-keylen-options-callback
+[`crypto.webcrypto.getRandomValues()`]: webcrypto.md#cryptogetrandomvaluestypedarray
 [`decipher.final()`]: crypto.md#decipherfinaloutputencoding
 [`decipher.setAuthTag()`]: crypto.md#deciphersetauthtagbuffer-encoding
 [`dns.lookup()`]: dns.md#dnslookuphostname-options-callback