1 files changed, 91 insertions, 55 deletions

diff --git a/lang/js/src/gpgmejs.js b/lang/js/src/gpgmejs.js
index f49361dc..3f6dc947 100644
--- a/lang/js/src/gpgmejs.js
+++ b/lang/js/src/gpgmejs.js
@@ -28,10 +28,62 @@ import { gpgme_error } from './Errors';
 import { GPGME_Keyring } from './Keyring';
 import { createSignature } from './Signature';
 
+/**
+ * @typedef {Object} decrypt_result
+ * @property {String} data The decrypted data
+ * @property {Boolean} base64 indicating whether data is base64 encoded.
+ * @property {Boolean} is_mime (optional) the data claims to be a MIME
+ * object.
+ * @property {String} file_name (optional) the original file name
+ * @property {signatureDetails} signatures Verification details for
+ * signatures
+ */
+
+/**
+ * @typedef {Object} signatureDetails
+ * @property {Boolean} all_valid Summary if all signatures are fully valid
+ * @property {Number} count Number of signatures found
+ * @property {Number} failures Number of invalid signatures
+ * @property {Array<GPGME_Signature>} signatures.good All valid signatures
+ * @property {Array<GPGME_Signature>} signatures.bad All invalid signatures
+ */
+
+/**
+ * @typedef {Object} encrypt_result The result of an encrypt operation
+ * @property {String} data The encrypted message
+ * @property {Boolean} base64 Indicating whether data is base64 encoded.
+ */
+
+/**
+ * @typedef { GPGME_Key | String | Object } inputKeys
+ * Accepts different identifiers of a gnupg Key that can be parsed by
+ * {@link toKeyIdArray}. Expected inputs are: One or an array of
+ * GPGME_Keys; one or an array of fingerprint strings; one or an array of
+ * openpgpjs Key objects.
+ */
+
+/**
+ * @typedef {Object} signResult The result of a signing operation
+ * @property {String} data The resulting data. Includes the signature in
+ *  clearsign mode
+ * @property {String} signature The detached signature (if in detached mode)
+ */
+
+/** @typedef {Object} verifyResult The result of a verification
+ * @property {Boolean} data: The verified data
+ * @property {Boolean} is_mime (optional) the data claims to be a MIME
+ * object.
+ * @property {String} file_name (optional) the original file name
+ * @property {signatureDetails} signatures Verification details for
+ * signatures
+ */
+
+/**
+ * The main entry point for gpgme.js.
+ * @class
+ */
 export class GpgME {
-    /**
-     * initializes GpgME by opening a nativeMessaging port
-     */
+
     constructor(){
     }
 
@@ -41,6 +93,9 @@ export class GpgME {
         }
     }
 
+    /**
+     * Accesses the {@link GPGME_Keyring}.
+     */
     get Keyring(){
         if (!this._Keyring){
             this._Keyring = new GPGME_Keyring;
@@ -49,23 +104,23 @@ export class GpgME {
     }
 
     /**
-     * Encrypt (and optionally sign) a Message
+     * Encrypt (and optionally sign) data
      * @param {String|Object} data text/data to be encrypted as String. Also
      * accepts Objects with a getText method
-     * @param  {GPGME_Key|String|Array<String>|Array<GPGME_Key>} publicKeys
+     * @param {inputKeys} publicKeys
      * Keys used to encrypt the message
-     * @param  {GPGME_Key|String|Array<String>|Array<GPGME_Key>} secretKeys
-     * (optional) Keys used to sign the message
+     * @param {inputKeys} secretKeys (optional) Keys used to sign the message.
+     * If Keys are present, the  operation requested is assumed to be 'encrypt
+     * and sign'
      * @param {Boolean} base64 (optional) The data will be interpreted as
-     * base64 encoded data
-     * @param {Boolean} armor (optional) Request the output as armored block
+     * base64 encoded data.
+     * @param {Boolean} armor (optional) Request the output as armored block.
      * @param {Boolean} wildcard (optional) If true, recipient information will
-     *  not be added to the message
-     * @param {Object} additional use additional gpg options
-     * (refer to src/permittedOperations)
-     * @returns {Promise<Object>} Encrypted message:
-     *   data: The encrypted message
-     *   base64: Boolean indicating whether data is base64 encoded.
+     * not be added to the message.
+     * @param {Object} additional use additional valid gpg options as defined
+     * in {@link permittedOperations}
+     * @returns {Promise<encrypt_result>} Object containing the encrypted
+     * message and additional info.
      * @async
      */
     encrypt(data, publicKeys, secretKeys, base64=false, armor=true,
@@ -105,28 +160,12 @@ export class GpgME {
     }
 
     /**
-    * Decrypt a Message
+    * Decrypts a Message
     * @param {String|Object} data text/data to be decrypted. Accepts Strings
     *  and Objects with a getText method
     * @param {Boolean} base64 (optional) false if the data is an armored block,
     *   true if it is base64 encoded binary data
-    * @returns {Promise<Object>} result: Decrypted Message and information
-    * @returns {String} result.data: The decrypted data.
-    * @returns {Boolean} result.base64: indicating whether data is base64
-    *   encoded.
-    * @returns {Boolean} result.is_mime: Indicating whether the data is a MIME
-    *   object.
-    * @returns {String} result.file_name: The optional original file name
-    * @returns {Object} message.signatures Verification details for signatures:
-    * @returns {Boolean} message.signatures.all_valid: true if all signatures
-    *   are valid
-    * @returns {Number} message.signatures.count: Number of signatures found
-    * @returns {Number} message.signatures.failures Number of invalid
-    *   signatures
-    * @returns {Array<Object>} message.signatures.signatures. Two arrays
-    *   (good & bad) of {@link GPGME_Signature} objects, offering further
-    *   information.
-    *
+    * @returns {Promise<decrypt_result>} Decrypted Message and information
     * @async
     */
     decrypt(data, base64=false){
@@ -169,16 +208,13 @@ export class GpgME {
     /**
      * Sign a Message
      * @param {String|Object} data text/data to be signed. Accepts Strings
-     * and Objects with a gettext methos
-     * @param {GPGME_Key|String|Array<String>|Array<GPGME_Key>} keys The
-     * key/keys to use for signing
-     * @param {*} mode The signing mode. Currently supported:
-     *      'clearsign': (default) The Message is embedded into the signature
-     *      'detached': The signature is stored separately
-     * @param {*} base64 input is considered base64
-     * @returns {Promise<Object>}
-     *    data: The resulting data. Includes the signature in clearsign mode
-     *    signature: The detached signature (if in detached mode)
+     * and Objects with a getText method.
+     * @param {inputKeys} keys The key/keys to use for signing
+     * @param {String} mode The signing mode. Currently supported:
+     *  'clearsign':The Message is embedded into the signature;
+     *  'detached': The signature is stored separately
+     * @param {Boolean} base64 input is considered base64
+     * @returns {Promise<signResult>}
      * @async
      */
     sign(data, keys, mode='clearsign', base64=false) {
@@ -221,20 +257,12 @@ export class GpgME {
     /**
      * Verifies data.
      * @param {String|Object} data text/data to be verified. Accepts Strings
-     * and Objects with a gettext method
+     * and Objects with a getText method
      * @param {String} (optional) A detached signature. If not present, opaque
      * mode is assumed
      * @param {Boolean} (optional) Data and signature are base64 encoded
-     * // TODO verify if signature really is assumed to be base64
-     * @returns {Promise<Object>} result:
-     * @returns {Boolean} result.data: The verified data
-     * @returns {Boolean} result.is_mime: The message claims it is MIME
-     * @returns {String} result.file_name: The optional filename of the message
-     * @returns {Boolean} result.all_valid: true if all signatures are valid
-     * @returns {Number} result.count: Number of signatures found
-     * @returns {Number} result.failures Number of unsuccessful signatures
-     * @returns {Array<Object>} result.signatures. Two arrays (good & bad) of
-     *      {@link GPGME_Signature} objects, offering further information.
+     * @returns {Promise<verifyResult>}
+     *@async
      */
     verify(data, signature, base64 = false){
         let msg = createMessage('verify');
@@ -275,7 +303,10 @@ export class GpgME {
 /**
  * Sets the data of the message, setting flags according on the data type
  * @param {GPGME_Message} message The message where this data will be set
- * @param {*} data The data to enter
+ * @param { String| Object } data The data to enter. Expects either a string of
+ * data, or an object with a getText method
+ * @returns {undefined| GPGME_Error} Error if not successful, nothing otherwise
+ * @private
  */
 function putData(message, data){
     if (!message || !(message instanceof GPGME_Message) ) {
@@ -301,6 +332,11 @@ function putData(message, data){
     }
 }
 
+/**
+ * Parses, validates and converts incoming objects into signatures.
+ * @param {Array<Object>} sigs
+ * @returns {signatureDetails} Details about the signatures
+ */
 function collectSignatures(sigs){
     if (!Array.isArray(sigs)){
         return gpgme_error('SIG_NO_SIGS');