Clean up async function JSDocs

src/cleartext.js

@@ -128,7 +128,7 @@ export class CleartextMessage {
  * @param {Object} options
  * @param {String} options.cleartextMessage - Text to be parsed
  * @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
- * @returns {CleartextMessage} New cleartext message object.
+ * @returns {Promise<CleartextMessage>} New cleartext message object.
  * @async
  * @static
  */

src/crypto/crypto.js

@@ -41,7 +41,7 @@ import { Curve } from './public_key/elliptic/curves';
  * @param {Object} publicParams - Algorithm-specific public key parameters
  * @param {Uint8Array} data - Data to be encrypted
  * @param {Uint8Array} fingerprint - Recipient fingerprint
- * @returns {Object} Encrypted session key parameters.
+ * @returns {Promise<Object>} Encrypted session key parameters.
  * @async
  */
 export async function publicKeyEncrypt(algo, publicParams, data, fingerprint) {
@@ -75,7 +75,7 @@ export async function publicKeyEncrypt(algo, publicParams, data, fingerprint) {
  * @param {Object} privateKeyParams - Algorithm-specific private key parameters
  * @param {Object} sessionKeyParams - Encrypted session key parameters
  * @param {Uint8Array} fingerprint - Recipient fingerprint
- * @returns {Uint8Array} Decrypted data.
+ * @returns {Promise<Uint8Array>} Decrypted data.
  * @async
  */
 export async function publicKeyDecrypt(algo, publicKeyParams, privateKeyParams, sessionKeyParams, fingerprint) {
@@ -253,7 +253,7 @@ export function serializeParams(algo, params) {
  * @param {module:enums.publicKey} algo - The public key algorithm
  * @param {Integer} bits - Bit length for RSA keys
  * @param {module:type/oid} oid - Object identifier for ECC keys
- * @returns {{ publicParams: {Object}, privateParams: {Object} }} The parameters referenced by name.
+ * @returns {Promise<{ publicParams: {Object}, privateParams: {Object} }>} The parameters referenced by name.
  * @async
  */
 export function generateParams(algo, bits, oid) {
@@ -344,7 +344,7 @@ export async function validateParams(algo, publicParams, privateParams) {
  * Generates a random byte prefix for the specified algorithm
  * See {@link https://tools.ietf.org/html/rfc4880#section-9.2|RFC 4880 9.2} for algorithms.
  * @param {module:enums.symmetric} algo - Symmetric encryption algorithm
- * @returns {Uint8Array} Random bytes with length equal to the block size of the cipher, plus the last two bytes repeated.
+ * @returns {Promise<Uint8Array>} Random bytes with length equal to the block size of the cipher, plus the last two bytes repeated.
  * @async
  */
 export async function getPrefixRandom(algo) {
@@ -357,7 +357,7 @@ export async function getPrefixRandom(algo) {
  * Generating a session key for the specified symmetric algorithm
  * See {@link https://tools.ietf.org/html/rfc4880#section-9.2|RFC 4880 9.2} for algorithms.
  * @param {module:enums.symmetric} algo - Symmetric encryption algorithm
- * @returns {Uint8Array} Random bytes as a string to be used as a key.
+ * @returns {Promise<Uint8Array>} Random bytes as a string to be used as a key.
  * @async
  */
 export function generateSessionKey(algo) {

src/crypto/pkcs1.js

@@ -49,7 +49,7 @@ hash_headers[11] = [0x30, 0x2d, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01,
  * Create padding with secure random data
  * @private
  * @param {Integer} length - Length of the padding in bytes
- * @returns {Uint8Array} Random padding.
+ * @returns {Promise<Uint8Array>} Random padding.
  * @async
  */
 async function getPKCS1Padding(length) {

src/crypto/public_key/dsa.js

@@ -38,7 +38,7 @@ import { isProbablePrime } from './prime';
  * @param {Uint8Array} p
  * @param {Uint8Array} q
  * @param {Uint8Array} x
- * @returns {{ r: Uint8Array, s: Uint8Array }}
+ * @returns {Promise<{ r: Uint8Array, s: Uint8Array >}}
  * @async
  */
 export async function sign(hashAlgo, hashed, g, p, q, x) {

src/crypto/public_key/elgamal.js

@@ -32,7 +32,7 @@ import { emeEncode, emeDecode } from '../pkcs1';
  * @param {Uint8Array} p
  * @param {Uint8Array} g
  * @param {Uint8Array} y
- * @returns {{ c1: Uint8Array, c2: Uint8Array }}
+ * @returns {Promise<{ c1: Uint8Array, c2: Uint8Array >}}
  * @async
  */
 export async function encrypt(data, p, g, y) {
@@ -59,7 +59,7 @@ export async function encrypt(data, p, g, y) {
  * @param {Uint8Array} c2
  * @param {Uint8Array} p
  * @param {Uint8Array} x
- * @returns {Uint8Array} Unpadded message.
+ * @returns {Promise<Uint8Array>} Unpadded message.
  * @async
  */
 export async function decrypt(c1, c2, p, x) {

src/crypto/public_key/elliptic/ecdsa.js

@@ -39,8 +39,10 @@ const nodeCrypto = util.getNodeCrypto();
  * @param {Uint8Array} publicKey - Public key
  * @param {Uint8Array} privateKey - Private key used to sign the message
  * @param {Uint8Array} hashed - The hashed message
- * @returns {{r: Uint8Array,
+ * @returns {Promise<{
- *            s: Uint8Array}}               Signature of the message
+ *   r: Uint8Array,
+ *   s: Uint8Array
+ * }>} Signature of the message
  * @async
  */
 export async function sign(oid, hashAlgo, message, publicKey, privateKey, hashed) {

src/crypto/public_key/elliptic/eddsa.js

@@ -37,8 +37,10 @@ nacl.hash = bytes => new Uint8Array(sha512().update(bytes).digest());
  * @param {Uint8Array} publicKey - Public key
  * @param {Uint8Array} privateKey - Private key used to sign the message
  * @param {Uint8Array} hashed - The hashed message
- * @returns {{r: Uint8Array,
+ * @returns {Promise<{
- *            s: Uint8Array}}               Signature of the message
+ *   r: Uint8Array,
+ *   s: Uint8Array
+ * }>} Signature of the message
  * @async
  */
 export async function sign(oid, hashAlgo, message, publicKey, privateKey, hashed) {

src/crypto/public_key/rsa.js

@@ -80,7 +80,7 @@ const RSAPublicKey = util.detectNode() ? asn1.define('RSAPubliceKey', function (
  * @param {Uint8Array} q - RSA private prime q
  * @param {Uint8Array} u - RSA private coefficient
  * @param {Uint8Array} hashed - Hashed message
- * @returns {Uint8Array} RSA Signature.
+ * @returns {Promise<Uint8Array>} RSA Signature.
  * @async
  */
 export async function sign(hashAlgo, data, n, e, d, p, q, u, hashed) {
@@ -129,7 +129,7 @@ export async function verify(hashAlgo, data, s, n, e, hashed) {
  * @param {Uint8Array} data - Message
  * @param {Uint8Array} n - RSA public modulus
  * @param {Uint8Array} e - RSA public exponent
- * @returns {Uint8Array} RSA Ciphertext.
+ * @returns {Promise<Uint8Array>} RSA Ciphertext.
  * @async
  */
 export async function encrypt(data, n, e) {
@@ -148,7 +148,7 @@ export async function encrypt(data, n, e) {
  * @param {Uint8Array} p - RSA private prime p
  * @param {Uint8Array} q - RSA private prime q
  * @param {Uint8Array} u - RSA private coefficient
- * @returns {String} RSA Plaintext.
+ * @returns {Promise<String>} RSA Plaintext.
  * @async
  */
 export async function decrypt(data, n, e, d, p, q, u) {

src/crypto/random.js

@@ -96,7 +96,7 @@ class RandomBuffer {
 /**
  * Retrieve secure random byte array of the specified length
  * @param {Integer} length - Length in bytes to generate
- * @returns {Uint8Array} Random byte array.
+ * @returns {Promise<Uint8Array>} Random byte array.
  * @async
  */
 export async function getRandomBytes(length) {
@@ -120,7 +120,7 @@ export async function getRandomBytes(length) {
  * Create a secure random BigInteger that is greater than or equal to min and less than max.
  * @param {module:BigInteger} min - Lower bound, included
  * @param {module:BigInteger} max - Upper bound, excluded
- * @returns {module:BigInteger} Random BigInteger.
+ * @returns {Promise<module:BigInteger>} Random BigInteger.
  * @async
  */
 export async function getRandomBigInteger(min, max) {

src/crypto/signature.js

@@ -16,7 +16,7 @@ import util from '../util';
  * See {@link https://tools.ietf.org/html/rfc4880#section-5.2.2|RFC 4880 5.2.2.}
  * @param {module:enums.publicKey} algo - Public key algorithm
  * @param {Uint8Array} signature - Data for which the signature was created
- * @returns {Object} True if signature is valid.
+ * @returns {Promise<Object>} True if signature is valid.
  * @async
  */
 export function parseSignatureParams(algo, signature) {
@@ -70,7 +70,7 @@ export function parseSignatureParams(algo, signature) {
  * @param {Object} publicParams - Algorithm-specific public key parameters
  * @param {Uint8Array} data - Data for which the signature was created
  * @param {Uint8Array} hashed - The hashed data
- * @returns {Boolean} True if signature is valid.
+ * @returns {Promise<Boolean>} True if signature is valid.
  * @async
  */
 export async function verify(algo, hashAlgo, signature, publicParams, data, hashed) {
@@ -116,7 +116,7 @@ export async function verify(algo, hashAlgo, signature, publicParams, data, hash
  * @param {Object} privateKeyParams - Algorithm-specific public and private key parameters
  * @param {Uint8Array} data - Data to be signed
  * @param {Uint8Array} hashed - The hashed data
- * @returns {Object} Signature                      Object containing named signature parameters.
+ * @returns {Promise<Object>} Signature                      Object containing named signature parameters.
  * @async
  */
 export async function sign(algo, hashAlgo, publicKeyParams, privateKeyParams, data, hashed) {

src/key/key.js

@@ -627,8 +627,10 @@ class Key {
    * @param {Date} [date] - Use the given date for verification instead of the current time
    * @param {Object} [userID] - User ID to get instead of the primary user, if it exists
    * @param {Object} [config] - Full configuration, defaults to openpgp.config
-   * @returns {Promise<{user: User,
+   * @returns {Promise<{
-   *                    selfCertification: SignaturePacket}>} The primary user and the self signature
+   *   user: User,
+   *   selfCertification: SignaturePacket
+   * }>} The primary user and the self signature
    * @async
    */
   async getPrimaryUser(date = new Date(), userID = {}, config = defaultConfig) {
@@ -862,8 +864,10 @@ class Key {
    * @param {Date} [date] - Use the given date for verification instead of the current time
    * @param {Object} [userID] - User ID to get instead of the primary user, if it exists
    * @param {Object} [config] - Full configuration, defaults to openpgp.config
-   * @returns {Promise<Array<{keyID: module:type/keyid~KeyID,
+   * @returns {Promise<Array<{
-   *                          valid: Boolean}>>}    List of signer's keyID and validity of signature
+   *   keyID: module:type/keyid~KeyID,
+   *   valid: Boolean
+   * }>>} List of signer's keyID and validity of signature
    * @async
    */
   async verifyPrimaryUser(keys, date, userID, config = defaultConfig) {
@@ -880,9 +884,11 @@ class Key {
    * - otherwise, verifies all certificates signed with given keys.
    * @param {Array<Key>} keys - array of keys to verify certificate signatures
    * @param {Object} [config] - Full configuration, defaults to openpgp.config
-   * @returns {Promise<Array<{userID: String,
+   * @returns {Promise<Array<{
+   *   userID: String,
    *   keyID: module:type/keyid~KeyID,
-   *                          valid: Boolean}>>} list of userID, signer's keyID and validity of signature
+   *   valid: Boolean
+   * }>>} List of userID, signer's keyID and validity of signature
    * @async
    */
   async verifyAllUsers(keys, config = defaultConfig) {

src/key/user.js

@@ -141,8 +141,10 @@ class User {
    * @param {Array<Key>} keys - Array of keys to verify certificate signatures
    * @param {Date} date - Use the given date instead of the current time
    * @param {Object} config - Full configuration
-   * @returns {Promise<Array<{keyID: module:type/keyid~KeyID,
+   * @returns {Promise<Array<{
-   *                          valid: Boolean}>>}   List of signer's keyID and validity of signature
+   *   keyID: module:type/keyid~KeyID,
+   *   valid: Boolean
+   * }>>} List of signer's keyID and validity of signature
    * @async
    */
   async verifyAllCertifications(primaryKey, keys, date = new Date(), config) {

src/message.js

@@ -158,8 +158,10 @@ export class Message {
    * @param {Array<Key>} [privateKeys] - Private keys with decrypted secret data
    * @param {Array<String>} [passwords] - Passwords used to decrypt
    * @param {Object} [config] - Full configuration, defaults to openpgp.config
-   * @returns {Promise<Array<{ data:      Uint8Array,
+   * @returns {Promise<Array<{
-                               algorithm: String }>>} array of object with potential sessionKey, algorithm pairs
+   *   data: Uint8Array,
+   *   algorithm: String
+   * }>>} array of object with potential sessionKey, algorithm pairs
    * @async
    */
   async decryptSessionKeys(privateKeys, passwords, config = defaultConfig) {
@@ -698,9 +700,11 @@ export async function createSignaturePackets(literalDataPacket, privateKeys, sig
  *                    i.e. check signature creation time < date < expiration time
  * @param {Boolean} [detached] - Whether to verify detached signature packets
  * @param {Object} [config] - Full configuration, defaults to openpgp.config
- * @returns {{keyID: module:type/keyid~KeyID,
+ * @returns {Promise<{
+ *   keyID: module:type/keyid~KeyID,
  *   signature: Promise<Signature>,
- *            verified: Promise<Boolean>}} signer's keyID and validity of signature
+ *   verified: Promise<Boolean>
+ * }>} signer's keyID and validity of signature
  * @async
  * @private
  */
@@ -772,9 +776,11 @@ async function createVerificationObject(signature, literalDataList, keys, date =
  *                    i.e. check signature creation time < date < expiration time
  * @param {Boolean} [detached] - Whether to verify detached signature packets
  * @param {Object} [config] - Full configuration, defaults to openpgp.config
- * @returns {Array<{keyID: module:type/keyid~KeyID,
+ * @returns {Promise<Array<{
+ *   keyID: module:type/keyid~KeyID,
  *   signature: Promise<Signature>,
- *            verified: Promise<Boolean>}>} list of signer's keyID and validity of signatures
+ *   verified: Promise<Boolean>
+ * }>>} list of signer's keyID and validity of signatures
  * @async
  * @private
  */
@@ -835,7 +841,7 @@ export async function readMessage({ armoredMessage, binaryMessage, config }) {
  * @param {String} [options.filename=""] - Name of the file (if any)
  * @param {Date} [options.date=current date] - Date of the message, or modification date of the file
  * @param {'utf8'|'binary'|'text'|'mime'} [options.format='utf8' if text is passed, 'binary' otherwise] - Data packet type
- * @returns {Message} New message object.
+ * @returns {Promise<Message>} New message object.
  * @async
  * @static
  */

src/openpgp.js

@@ -550,7 +550,8 @@ function toArray(param) {
  * @param {Object} data - the data to convert
  * @param {'web'|'ponyfill'|'node'|false} streaming - Whether to return a ReadableStream, and of what type
  * @param {'utf8'|'binary'} [encoding] - How to return data in Node Readable streams
- * @returns {Object} The data in the respective format.
+ * @returns {Promise<Object>} The data in the respective format.
+ * @async
  * @private
  */
 async function convertStream(data, streaming, encoding = 'utf8') {
@@ -596,6 +597,7 @@ function linkStreams(result, message) {
 /**
  * Wait until signature objects have been verified
  * @param {Object} signatures - list of signatures
+ * @async
  * @private
  */
 async function prepareSignatures(signatures) {

src/packet/aead_encrypted_data.js

@@ -119,7 +119,7 @@ class AEADEncryptedDataPacket {
    * @param {encrypt|decrypt} fn - Whether to encrypt or decrypt
    * @param {Uint8Array} key - The session key used to en/decrypt the payload
    * @param {Uint8Array | ReadableStream<Uint8Array>} data - The data to en/decrypt
-   * @returns {Uint8Array | ReadableStream<Uint8Array>}
+   * @returns {Promise<Uint8Array | ReadableStream<Uint8Array>>}
    * @async
    */
   async crypt(fn, key, data) {

src/packet/literal_data.js

@@ -117,7 +117,8 @@ class LiteralDataPacket {
    * Parsing function for a literal data packet (tag 11).
    *
    * @param {Uint8Array | ReadableStream<Uint8Array>} input - Payload of a tag 11 packet
-   * @returns {LiteralDataPacket} Object representation.
+   * @returns {Promise<LiteralDataPacket>} Object representation.
+   * @async
    */
   async read(bytes) {
     await stream.parse(bytes, async reader => {

src/signature.js

@@ -59,7 +59,7 @@ export class Signature {
  * @param {String} [options.armoredSignature] - Armored signature to be parsed
  * @param {Uint8Array} [options.binarySignature] - Binary signature to be parsed
  * @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
- * @returns {Signature} New signature object.
+ * @returns {Promise<Signature>} New signature object.
  * @async
  * @static
  */

src/type/s2k.js

@@ -143,8 +143,9 @@ class S2K {
    * Produces a key using the specified passphrase and the defined
    * hashAlgorithm
    * @param {String} passphrase - Passphrase containing user input
-   * @returns {Uint8Array} Produced key with a length corresponding to.
+   * @returns {Promise<Uint8Array>} Produced key with a length corresponding to.
    * hashAlgorithm hash length
+   * @async
    */
   async produceKey(passphrase, numBytes) {
     passphrase = util.encodeUTF8(passphrase);