From 29dbf824638d72d814244598c07d6e34aadf0644 Mon Sep 17 00:00:00 2001
From: Jeremy Huang <jieyanhuang@gmail.com>
Date: Mon, 16 Oct 2017 16:16:58 +0800
Subject: [PATCH 1/2] doc: clarify documentation in crypto

Clarify on the return values for crypto.publicEncrypt and similar
functions

Fixes: https://github.com/nodejs/node/issues/12946
---
 doc/api/crypto.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index fd2213f8b5527e..8655fd9c93629f 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -1687,12 +1687,15 @@ added: v0.11.14
     `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING`,
     `RSA_PKCS1_PADDING`, or `crypto.constants.RSA_PKCS1_OAEP_PADDING`.
 - `buffer` {Buffer | TypedArray | DataView}
+- Returns: {Buffer}
 
 Decrypts `buffer` with `privateKey`.
 
 `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`.
 
+Returns a new `Buffer` with the decrypted content.
+
 ### crypto.privateEncrypt(privateKey, buffer)
 <!-- YAML
 added: v1.1.0
@@ -1704,12 +1707,15 @@ added: v1.1.0
     `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING` or
     `RSA_PKCS1_PADDING`.
 - `buffer` {Buffer | TypedArray | DataView}
+- Returns: {Buffer}
 
 Encrypts `buffer` with `privateKey`.
 
 `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`.
 
+Returns a new `Buffer` with the encrypted content.
+
 ### crypto.publicDecrypt(publicKey, buffer)
 <!-- YAML
 added: v1.1.0
@@ -1721,6 +1727,7 @@ added: v1.1.0
     `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING` or
     `RSA_PKCS1_PADDING`.
 - `buffer` {Buffer | TypedArray | DataView}
+- Returns: {Buffer}
 
 Decrypts `buffer` with `publicKey`.
 
@@ -1730,6 +1737,8 @@ treated as the key with no passphrase and will use `RSA_PKCS1_PADDING`.
 Because RSA public keys can be derived from private keys, a private key may
 be passed instead of a public key.
 
+Returns a new `Buffer` with the decrypted content.
+
 ### crypto.publicEncrypt(publicKey, buffer)
 <!-- YAML
 added: v0.11.14
@@ -1741,6 +1750,7 @@ added: v0.11.14
     `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING`,
     `RSA_PKCS1_PADDING`, or `crypto.constants.RSA_PKCS1_OAEP_PADDING`.
 - `buffer` {Buffer | TypedArray | DataView}
+- Returns: {Buffer}
 
 Encrypts the content of `buffer` with `publicKey` and returns a new
 [`Buffer`][] with encrypted content.
@@ -1751,6 +1761,8 @@ treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
 Because RSA public keys can be derived from private keys, a private key may
 be passed instead of a public key.
 
+Returns a new `Buffer` with the encrypted content.
+
 ### crypto.randomBytes(size[, callback])
 <!-- YAML
 added: v0.5.8

From 5b4aa7b447744090413a02f3ce6002a23b344050 Mon Sep 17 00:00:00 2001
From: Jeremy Huang <jieyanhuang@gmail.com>
Date: Mon, 16 Oct 2017 17:43:16 +0800
Subject: [PATCH 2/2] doc: clean up documentation

---
 doc/api/crypto.md | 16 ++++------------
 1 file changed, 4 insertions(+), 12 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 8655fd9c93629f..9aea286fab2dec 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -1687,15 +1687,13 @@ added: v0.11.14
     `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING`,
     `RSA_PKCS1_PADDING`, or `crypto.constants.RSA_PKCS1_OAEP_PADDING`.
 - `buffer` {Buffer | TypedArray | DataView}
-- Returns: {Buffer}
+- Returns: {Buffer} A new `Buffer` with the decrypted content.
 
 Decrypts `buffer` with `privateKey`.
 
 `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`.
 
-Returns a new `Buffer` with the decrypted content.
-
 ### crypto.privateEncrypt(privateKey, buffer)
 <!-- YAML
 added: v1.1.0
@@ -1707,15 +1705,13 @@ added: v1.1.0
     `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING` or
     `RSA_PKCS1_PADDING`.
 - `buffer` {Buffer | TypedArray | DataView}
-- Returns: {Buffer}
+- Returns: {Buffer} A new `Buffer` with the encrypted content.
 
 Encrypts `buffer` with `privateKey`.
 
 `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`.
 
-Returns a new `Buffer` with the encrypted content.
-
 ### crypto.publicDecrypt(publicKey, buffer)
 <!-- YAML
 added: v1.1.0
@@ -1727,7 +1723,7 @@ added: v1.1.0
     `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING` or
     `RSA_PKCS1_PADDING`.
 - `buffer` {Buffer | TypedArray | DataView}
-- Returns: {Buffer}
+- Returns: {Buffer} A new `Buffer` with the decrypted content.
 
 Decrypts `buffer` with `publicKey`.
 
@@ -1737,8 +1733,6 @@ treated as the key with no passphrase and will use `RSA_PKCS1_PADDING`.
 Because RSA public keys can be derived from private keys, a private key may
 be passed instead of a public key.
 
-Returns a new `Buffer` with the decrypted content.
-
 ### crypto.publicEncrypt(publicKey, buffer)
 <!-- YAML
 added: v0.11.14
@@ -1750,7 +1744,7 @@ added: v0.11.14
     `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING`,
     `RSA_PKCS1_PADDING`, or `crypto.constants.RSA_PKCS1_OAEP_PADDING`.
 - `buffer` {Buffer | TypedArray | DataView}
-- Returns: {Buffer}
+- Returns: {Buffer} A new `Buffer` with the encrypted content.
 
 Encrypts the content of `buffer` with `publicKey` and returns a new
 [`Buffer`][] with encrypted content.
@@ -1761,8 +1755,6 @@ treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
 Because RSA public keys can be derived from private keys, a private key may
 be passed instead of a public key.
 
-Returns a new `Buffer` with the encrypted content.
-
 ### crypto.randomBytes(size[, callback])
 <!-- YAML
 added: v0.5.8