From 2275db979592a16dfaa92f5055935d7d3ed720a1 Mon Sep 17 00:00:00 2001
From: BIGSUS24 <152616194+BIGSUS24@users.noreply.github.com>
Date: Sat, 26 Sep 2026 01:56:20 +0530
Subject: [PATCH] doc: document return values of crypto methods

`hash.update()`, `hmac.update()`, `sign.update()`, `verify.update()`,
`diffieHellman.setPrivateKey()`, `diffieHellman.setPublicKey()` and
`ecdh.setPrivateKey()` all return the object they were called on, so
calls can be chained, but none of them documents a return value.
Sibling methods in the same sections, such as `hash.copy()`,
`hash.digest()` and `verify.verify()`, already document theirs.

Verified against lib/internal/crypto/hash.js, sig.js and
diffiehellman.js, where each of these returns `this`;
`Hmac.prototype.update` and `Verify.prototype.update` are aliases of
the `Hash` and `Sign` versions, and `ECDH.prototype.setPrivateKey` is
an alias of the `DiffieHellman` version. Also verified at runtime on
v22.14.0 that each call returns the receiving object.

`ecdh.setPublicKey()` returns the same way but is left undocumented
here because it is deprecated.

Signed-off-by: BIGSUS24 <152616194+BIGSUS24@users.noreply.github.com>
Assisted-by: a closed-source coding agent
---
 doc/api/crypto.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index cafb38391b7..d3aee5afdf8 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -1488,6 +1488,7 @@ added: v0.5.0
 
 * `privateKey` {string|ArrayBuffer|Buffer|TypedArray|DataView}
 * `encoding` {string} The [encoding][] of the `privateKey` string.
+* Returns: {DiffieHellman} The `DiffieHellman` object itself.
 
 Sets the Diffie-Hellman private key. If the `encoding` argument is provided,
 `privateKey` is expected
@@ -1506,6 +1507,7 @@ added: v0.5.0
 
 * `publicKey` {string|ArrayBuffer|Buffer|TypedArray|DataView}
 * `encoding` {string} The [encoding][] of the `publicKey` string.
+* Returns: {DiffieHellman} The `DiffieHellman` object itself.
 
 Sets the Diffie-Hellman public key. If the `encoding` argument is provided,
 `publicKey` is expected
@@ -1791,6 +1793,7 @@ added: v0.11.14
 
 * `privateKey` {string|ArrayBuffer|Buffer|TypedArray|DataView}
 * `encoding` {string} The [encoding][] of the `privateKey` string.
+* Returns: {ECDH} The `ECDH` object itself.
 
 Sets the EC Diffie-Hellman private key.
 If `encoding` is provided, `privateKey` is expected
@@ -2085,6 +2088,7 @@ changes:
 
 * `data` {string|Buffer|TypedArray|DataView}
 * `inputEncoding` {string} The [encoding][] of the `data` string.
+* Returns: {Hash} The `Hash` object itself.
 
 Updates the hash content with the given `data`, the encoding of which
 is given in `inputEncoding`.
@@ -2245,6 +2249,7 @@ changes:
 
 * `data` {string|Buffer|TypedArray|DataView}
 * `inputEncoding` {string} The [encoding][] of the `data` string.
+* Returns: {Hmac} The `Hmac` object itself.
 
 Updates the `Hmac` content with the given `data`, the encoding of which
 is given in `inputEncoding`.
@@ -2828,6 +2833,7 @@ changes:
 
 * `data` {string|Buffer|TypedArray|DataView}
 * `inputEncoding` {string} The [encoding][] of the `data` string.
+* Returns: {Sign} The `Sign` object itself.
 
 Updates the `Sign` content with the given `data`, the encoding of which
 is given in `inputEncoding`.
@@ -2870,6 +2876,7 @@ changes:
 
 * `data` {string|Buffer|TypedArray|DataView}
 * `inputEncoding` {string} The [encoding][] of the `data` string.
+* Returns: {Verify} The `Verify` object itself.
 
 Updates the `Verify` content with the given `data`, the encoding of which
 is given in `inputEncoding`.