doc: document return values of crypto methods

[BIGSUS24]

Seven crypto methods return the object they were called on, so calls can be chained, but none of them documents a return value:

Method	Returns
hash.update()	{Hash}
hmac.update()	{Hmac}
sign.update()	{Sign}
verify.update()	{Verify}
diffieHellman.setPrivateKey()	{DiffieHellman}
diffieHellman.setPublicKey()	{DiffieHellman}
ecdh.setPrivateKey()	{ECDH}

Sibling methods in the same sections already document theirs — hash.copy() gives Returns: {Hash}, hash.digest() gives Returns: {Buffer | string}, verify.verify() gives Returns: {boolean} — so this is an inconsistency inside crypto.md.

The chaining is worth stating explicitly because hash.copy() also returns {Hash} but returns a new object, whereas hash.update() returns the same instance. The wording says "the Hash object itself" to keep those apart.

How I verified this

Against the source, on current main:

• lib/internal/crypto/hash.js: Hash.prototype.update ends with return this;, and Hmac.prototype.update = Hash.prototype.update;.
• lib/internal/crypto/sig.js: Sign.prototype.update ends with return this;, and Verify.prototype.update = Sign.prototype.update;.
• lib/internal/crypto/diffiehellman.js: DiffieHellman.prototype.setPublicKey and setPrivateKey both end with return this;, and ECDH.prototype.setPrivateKey = DiffieHellman.prototype.setPrivateKey;.

At runtime on v22.14.0, each of the seven calls returned the receiving object (assert.strictEqual(obj.method(...), obj) passed for all seven).

Not included

ecdh.setPublicKey() behaves the same way, but it's deprecated (ECDH.prototype.setPublicKey is wrapped in deprecate()), so I'd rather not add new detail to it. Say the word if you'd like it documented too.

---

Disclosure per AGENTS.md: I used a coding agent (Claude Code) to scan doc/api/*.md against lib/ for documented methods with undocumented return values. I read each hit in the source myself and ran the runtime checks above before opening this; the exclusions above are my own call.

[nodejs-github-bot]

Review requested:

• @nodejs/crypto

[Copilot]

Copilot review overview

🟢 Approval recommended

Documentation changes align the API reference with implementation behavior, with no unresolved issues.

Review effort: Lite
Findings: None

What changed in this PR

Documents return values for seven chainable crypto methods.

Changes:

• Adds return annotations for hash, HMAC, signing, and verification updates.
• Documents return values for Diffie-Hellman and ECDH setters.
• Clarifies that methods return the same object instance.

File	Description
doc/​api/​crypto.md	Documents the objects returned by seven methods.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[panva]

just the * Returns: {...} if fine. The prose can go in my opinion.