doc: improve asymmetric crypto docs

Refs: #22792

PR-URL: #22820
Reviewed-By: Tobias Nießen <[email protected]>
Reviewed-By: Minwoo Jung <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>

Author: addaleax

doc/api/crypto.md

@@ -1912,7 +1912,8 @@ added: v0.11.14
 * `buffer` {Buffer | TypedArray | DataView}
 * Returns: {Buffer} A new `Buffer` with the decrypted content.
 
-Decrypts `buffer` with `privateKey`.
+Decrypts `buffer` with `privateKey`. `buffer` was previously encrypted using
+the corresponding public key, for example using [`crypto.publicEncrypt()`][].
 
 `privateKey` can be an object or a string. If `privateKey` is a string, it is
 treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
@@ -1930,7 +1931,8 @@ added: v1.1.0
 * `buffer` {Buffer | TypedArray | DataView}
 * Returns: {Buffer} A new `Buffer` with the encrypted content.
 
-Encrypts `buffer` with `privateKey`.
+Encrypts `buffer` with `privateKey`. The returned data can be decrypted using
+the corresponding public key, for example using [`crypto.publicDecrypt()`][].
 
 `privateKey` can be an object or a string. If `privateKey` is a string, it is
 treated as the key with no passphrase and will use `RSA_PKCS1_PADDING`.
@@ -1948,7 +1950,8 @@ added: v1.1.0
 * `buffer` {Buffer | TypedArray | DataView}
 * Returns: {Buffer} A new `Buffer` with the decrypted content.
 
-Decrypts `buffer` with `key`.
+Decrypts `buffer` with `key`.`buffer` was previously encrypted using
+the corresponding private key, for example using [`crypto.privateEncrypt()`][].
 
 `key` can be an object or a string. If `key` is a string, it is treated as
 the key with no passphrase and will use `RSA_PKCS1_PADDING`.
@@ -1971,7 +1974,8 @@ added: v0.11.14
 * Returns: {Buffer} A new `Buffer` with the encrypted content.
 
 Encrypts the content of `buffer` with `key` and returns a new
-[`Buffer`][] with encrypted content.
+[`Buffer`][] with encrypted content. The returned data can be decrypted using
+the corresponding private key, for example using [`crypto.privateDecrypt()`][].
 
 `key` can be an object or a string. If `key` is a string, it is treated as
 the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
@@ -2765,6 +2769,10 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
 [`crypto.createVerify()`]: #crypto_crypto_createverify_algorithm_options
 [`crypto.getCurves()`]: #crypto_crypto_getcurves
 [`crypto.getHashes()`]: #crypto_crypto_gethashes
+[`crypto.privateDecrypt()`]: #crypto_crypto_privatedecrypt_privatekey_buffer
+[`crypto.privateEncrypt()`]: #crypto_crypto_privateencrypt_privatekey_buffer
+[`crypto.publicDecrypt()`]: #crypto_crypto_publicdecrypt_key_buffer
+[`crypto.publicEncrypt()`]: #crypto_crypto_publicencrypt_key_buffer
 [`crypto.randomBytes()`]: #crypto_crypto_randombytes_size_callback
 [`crypto.randomFill()`]: #crypto_crypto_randomfill_buffer_offset_size_callback
 [`crypto.scrypt()`]: #crypto_crypto_scrypt_password_salt_keylen_options_callback