From 1c618166fcd296b4e95f3a6ea9c415d3dca5ce0a Mon Sep 17 00:00:00 2001
From: Maximilian Krambach <maximilian.krambach@intevation.de>
Date: Wed, 5 Sep 2018 18:46:28 +0200
Subject: [PATCH] js: documentation cleanup

--
---
 lang/js/jsdoc.conf        |   2 +-
 lang/js/jsdoc_index.md    |  50 ++++++++++++++++++
 lang/js/src/Connection.js |  11 ++--
 lang/js/src/Errors.js     |  10 ++--
 lang/js/src/Helpers.js    |  24 +++++----
 lang/js/src/Key.js        |  69 ++++++++++++++++---------
 lang/js/src/Keyring.js    |  10 ++--
 lang/js/src/Message.js    |  18 ++++---
 lang/js/src/Signature.js  |  11 ++--
 lang/js/src/gpgmejs.js    | 103 ++++++++++++++++++++++----------------
 lang/js/src/index.js      |   8 +--
 11 files changed, 215 insertions(+), 101 deletions(-)
 create mode 100644 lang/js/jsdoc_index.md

diff --git a/lang/js/jsdoc.conf b/lang/js/jsdoc.conf
index 12ae35e9..976f4e41 100644
--- a/lang/js/jsdoc.conf
+++ b/lang/js/jsdoc.conf
@@ -4,7 +4,7 @@
         "dictionaries": ["jsdoc"]
     },
     "source": {
-        "include": ["./src"],
+        "include": ["jsdoc_index.md", "./src"],
         "includePattern": ".+\\.js(doc|x)?$",
         "excludePattern": "(^|\\/|\\\\)_"
     },
diff --git a/lang/js/jsdoc_index.md b/lang/js/jsdoc_index.md
new file mode 100644
index 00000000..b7371ad5
--- /dev/null
+++ b/lang/js/jsdoc_index.md
@@ -0,0 +1,50 @@
+Using gpgme.js
+---------------
+At first, make sure that the environment you want to use gpgme.js in has access
+and permissions for nativeMessaging, and gpgme-json installed. For details,
+see the README.
+
+The library itself is started via the {@link init} method. This will test the
+nativeMessaging connection, and then resolve into an Object offering
+the top level API:
+
+* [encrypt]{@link GpgME#encrypt}
+* [decrypt]{@link GpgME#decrypt}
+* [sign]{@link GpgME#sign}
+* [verify]{@link GpgME#verify}
+* [Keyring]{@link GPGME_Keyring}
+
+```
+gpgmejs.init()
+    .then(function(GPGME) {
+        // using GPGME
+    }, function(error){
+        // error handling;
+    })
+```
+
+All methods that require communication with nativeMessaging are asynchronous,
+using Promises. Rejections will be instances of {@link GPGME_Error}.
+
+An exaeption are Keys, which can be initialized in a 'sync' mode, allowing them
+to be cached and used synchronously until manually refreshed.
+
+Keyring and Keys
+----------------
+The gnupg keys can be accessed via the [Keyring]{@link GPGME_Keyring}.
+
+The Keyring offers the methods for accessing information on all Keys known to
+gnupg.
+
+**Due to security constraints, the javascript-binding currently only offers
+limited support for secret-Key interaction.**
+
+The existance of secret Keys is not secret, and those secret Keys can be used
+for signing, but Operations that may expose, modify or delete secret Keys are
+not supported.
+
+* [getKeysArmored]{@link GPGME_Keyring#getKeysArmored}
+* [getKeys]{@link GPGME_Keyring#getKeys}
+* [getDefaultKey]{@link GPGME_Keyring#getDefaultKey}
+* [generateKey]{@link GPGME_Keyring#generateKey}
+* [deleteKey]{@link GPGME_Keyring#deleteKey}
diff --git a/lang/js/src/Connection.js b/lang/js/src/Connection.js
index a421985a..4055da6a 100644
--- a/lang/js/src/Connection.js
+++ b/lang/js/src/Connection.js
@@ -35,6 +35,7 @@ import { decode, atobArray, Utf8ArrayToStr } from './Helpers';
  * are finished. For a new request, a new port will open, to avoid mixing
  * contexts.
  * @class
+ * @private
  */
 export class Connection{
 
@@ -58,6 +59,7 @@ export class Connection{
     * @property {String} gpgme Version number of gpgme
     * @property {Array<Object>} info Further information about the backend
     * and the used applications (Example:
+    * <pre>
     * {
     *          "protocol":     "OpenPGP",
     *          "fname":        "/usr/bin/gpg",
@@ -65,6 +67,7 @@ export class Connection{
     *          "req_version":  "1.4.0",
     *          "homedir":      "default"
     * }
+    * </pre>
     */
 
     /**
@@ -99,12 +102,14 @@ export class Connection{
     }
 
     /**
-     * Sends a {@link GPGME_Message} via tghe nativeMessaging port. It
+     * Sends a {@link GPGME_Message} via the nativeMessaging port. It
      * resolves with the completed answer after all parts have been
      * received and reassembled, or rejects with an {@link GPGME_Error}.
      *
      * @param {GPGME_Message} message
-     * @returns {Promise<Object>} The collected answer
+     * @returns {Promise<*>} The collected answer, depending on the messages'
+     * operation
+     * @private
      * @async
      */
     post (message){
@@ -182,7 +187,7 @@ export class Connection{
 /**
  * A class for answer objects, checking and processing the return messages of
  * the nativeMessaging communication.
- * @protected
+ * @private
  */
 class Answer{
 
diff --git a/lang/js/src/Errors.js b/lang/js/src/Errors.js
index 145c3a59..2f66c83d 100644
--- a/lang/js/src/Errors.js
+++ b/lang/js/src/Errors.js
@@ -120,8 +120,9 @@ export const err_list = {
 /**
  * Checks the given error code and returns an {@link GPGME_Error} error object
  * with some information about meaning and origin
- * @param {*} code Error code. Should be in err_list or 'GNUPG_ERROR'
- * @param {*} info Error message passed through if code is 'GNUPG_ERROR'
+ * @param {String} code Error code as defined in {@link err_list}.
+ * @param {String} info Possible additional error message to pass through.
+ * Currently used for errors sent as answer by gnupg via a native Message port
  * @returns {GPGME_Error}
  */
 export function gpgme_error (code = 'GENERIC_ERROR', info){
@@ -144,10 +145,13 @@ export function gpgme_error (code = 'GENERIC_ERROR', info){
 
 /**
  * An error class with additional info about the origin of the error, as string
+ * It is created by {@link gpgme_error}, and its' codes are defined in
+ * {@link err_list}.
+ *
  * @property {String} code Short description of origin and type of the error
  * @property {String} msg Additional info
- * @class
  * @protected
+ * @class
  * @extends Error
  */
 class GPGME_Error extends Error{
diff --git a/lang/js/src/Helpers.js b/lang/js/src/Helpers.js
index 952c09fc..f370fe60 100644
--- a/lang/js/src/Helpers.js
+++ b/lang/js/src/Helpers.js
@@ -24,11 +24,12 @@
 import { gpgme_error } from './Errors';
 
 /**
- * Tries to return an array of fingerprints, either from input fingerprints or
- * from Key objects (openpgp Keys or GPGME_Keys are both accepted).
+ * Helper function that tries to return an array of fingerprints, either from
+ * input fingerprints or from Key objects (openpgp Keys or GPGME_Keys are both
+ * accepted).
  *
- * @param {Object | Array<Object> | String | Array<String>} input
- * @returns {Array<String>} Array of fingerprints, or an empty array
+ * @param {Object | Object[] | String | String[] } input
+ * @returns {String[]} Array of fingerprints, or an empty array
  */
 export function toKeyIdArray (input){
     if (!input){
@@ -90,7 +91,7 @@ function hextest (key, len){
 }
 
 /**
- * check if the input is a valid Fingerprint
+ * Checks if the input is a valid Fingerprint
  *      (Hex string with a length of 40 characters)
  * @param {String} value to check
  * @returns {Boolean} true if value passes test
@@ -110,8 +111,9 @@ export function isLongId (value){
 }
 
 /**
- * Recursively decodes input (utf8) to output (utf-16; javascript) strings
+ * Recursively decodes input (utf8) to output (utf-16; javascript) strings.
  * @param {Object | Array | String} property
+ * @private
  */
 export function decode (property){
     if (typeof property === 'string'){
@@ -145,9 +147,10 @@ export function decode (property){
 
 /**
  * Turns a base64 encoded string into an uint8 array
+ * adapted from https://gist.github.com/borismus/1032746
  * @param {String} base64 encoded String
  * @returns {Uint8Array}
- * adapted from https://gist.github.com/borismus/1032746
+ * @private
  */
 export function atobArray (base64) {
     if (typeof (base64) !== 'string'){
@@ -164,8 +167,7 @@ export function atobArray (base64) {
 
 /**
  * Turns a Uint8Array into an utf8-String
- * @param {*} array Uint8Array
- * @returns {String}
+ * <pre>
  * Taken and slightly adapted from
  *  http://www.onicos.com/staff/iz/amuse/javascript/expert/utf.txt
  * (original header:
@@ -176,6 +178,10 @@ export function atobArray (base64) {
  *   LastModified: Dec 25 1999
  *   This library is free.  You can redistribute it and/or modify it.
  *  )
+ * </pre>
+ * @param {*} array Uint8Array
+ * @returns {String}
+ * @private
  */
 export function Utf8ArrayToStr (array) {
     let out, i, len, c, char2, char3;
diff --git a/lang/js/src/Key.js b/lang/js/src/Key.js
index d0f87eda..7f0554c4 100644
--- a/lang/js/src/Key.js
+++ b/lang/js/src/Key.js
@@ -21,6 +21,7 @@
  *     Maximilian Krambach <mkrambach@intevation.de>
  */
 
+
 import { isFingerprint, isLongId } from './Helpers';
 import { gpgme_error } from './Errors';
 import { createMessage } from './Message';
@@ -50,11 +51,26 @@ export function createKey (fingerprint, async = false, data){
 }
 
 /**
- * Represents the Keys as stored in the gnupg backend
- * It allows to query almost all information defined in gpgme Key Objects
- * Refer to {@link validKeyProperties} for available information, and the gpgme
- * documentation on their meaning
- * (https://www.gnupg.org/documentation/manuals/gpgme/Key-objects.html)
+ * Represents the Keys as stored in the gnupg backend. A key is defined by a
+ * fingerprint.
+ * A key cannot be directly created via the new operator, please use
+ * {@link createKey} instead.
+ * A GPGME_Key object allows to query almost all information defined in gpgme
+ * Keys. It offers two modes, async: true/false. In async mode, Key properties
+ * with the exception of the fingerprint will be queried from gnupg on each
+ * call, making the operation up-to-date, the answers will be Promises, and
+ * the performance will likely suffer. In Sync modes, all information except
+ * for the armored Key export will be cached and can be refreshed by
+ * [refreshKey]{@link GPGME_Key#refreshKey}.
+ *
+ * <pre>
+ * see also:
+ *      {@link GPGME_UserId} user Id objects
+ *      {@link GPGME_Subkey} subKey objects
+ * </pre>
+ * For other Key properteis, refer to {@link validKeyProperties},
+ * and to the [gpgme documentation]{@link https://www.gnupg.org/documentation/manuals/gpgme/Key-objects.html}
+ * for meanings and further details.
  *
  * @class
  */
@@ -63,7 +79,8 @@ class GPGME_Key {
     constructor (fingerprint, async, data){
 
         /**
-         * @property {Boolean} If true, most answers will be asynchronous
+         * @property {Boolean} _async If true, the Key was initialized without
+         * cached data
          */
         this._async = async;
 
@@ -79,10 +96,13 @@ class GPGME_Key {
      * Query any property of the Key listed in {@link validKeyProperties}
      * @param {String} property property to be retreived
      * @returns {Boolean| String | Date | Array | Object}
-     * the value of the property. If the Key is set to Async, the value
-     * will be fetched from gnupg and resolved as a Promise. If Key is not
-     * async, the armored property is not available (it can still be
-     * retrieved asynchronously by {@link Key.getArmor})
+     * @returns {Promise<Boolean| String | Date | Array | Object>} (if in async
+     * mode)
+     * <pre>
+     * Returns the value of the property requested. If the Key is set to async,
+     * the value will be fetched from gnupg and resolved as a Promise. If Key
+     * is not  async, the armored property is not available (it can still be
+     * retrieved asynchronously by [getArmor]{@link GPGME_Key#getArmor})
      */
     get (property) {
         if (this._async === true) {
@@ -108,11 +128,11 @@ class GPGME_Key {
     }
 
     /**
-     * Reloads the Key information from gnupg. This is only useful if you
+     * Reloads the Key information from gnupg. This is only useful if the Key
      * use the GPGME_Keys cached. Note that this is a performance hungry
      * operation. If you desire more than a few refreshs, it may be
-     * advisable to run {@link Keyring.getKeys} instead.
-     * @returns {Promise<GPGME_Key|GPGME_Error>}
+     * advisable to run [Keyring.getKeys]{@link Keyring#getKeys} instead.
+     * @returns {Promise<GPGME_Key>}
      * @async
      */
     refreshKey () {
@@ -155,7 +175,7 @@ class GPGME_Key {
      * Query the armored block of the Key directly from gnupg. Please note
      * that this will not get you any export of the secret/private parts of
      * a Key
-     * @returns {Promise<String|GPGME_Error>}
+     * @returns {Promise<String>}
      * @async
      */
     getArmor () {
@@ -179,10 +199,10 @@ class GPGME_Key {
      * Find out if the Key is part of a Key pair including public and
      * private key(s). If you want this information about more than a few
      * Keys in synchronous mode, it may be advisable to run
-     * {@link Keyring.getKeys} instead, as it performs faster in bulk
-     * querying this state.
-     * @returns {Promise<Boolean|GPGME_Error>} True if a private Key is
-     * available in the gnupg Keyring.
+     * [Keyring.getKeys]{@link Keyring#getKeys} instead, as it performs faster
+     * in bulk querying.
+     * @returns {Promise<Boolean>} True if a private Key is available in the
+     * gnupg Keyring.
      * @async
      */
     getGnupgSecretState (){
@@ -216,9 +236,10 @@ class GPGME_Key {
 
     /**
      * Deletes the (public) Key from the GPG Keyring. Note that a deletion
-     * of a secret key is not supported by the native backend.
-     * @returns {Promise<Boolean|GPGME_Error>} Success if key was deleted,
-     * rejects with a GPG error otherwise.
+     * of a secret key is not supported by the native backend, and gnupg will
+     * refuse to delete a Key if there is still a secret/private Key present
+     * to that public Key
+     * @returns {Promise<Boolean>} Success if key was deleted.
      */
     delete (){
         const me = this;
@@ -245,7 +266,8 @@ class GPGME_Key {
 }
 
 /**
- * Representing a subkey of a Key.
+ * Representing a subkey of a Key. See {@link validSubKeyProperties} for
+ * possible properties.
  * @class
  * @protected
  */
@@ -300,7 +322,8 @@ class GPGME_Subkey {
 }
 
 /**
- * Representing user attributes associated with a Key or subkey
+ * Representing user attributes associated with a Key or subkey. See
+ * {@link validUserIdProperties} for possible properties.
  * @class
  * @protected
  */
diff --git a/lang/js/src/Keyring.js b/lang/js/src/Keyring.js
index 0c64f337..e223284b 100644
--- a/lang/js/src/Keyring.js
+++ b/lang/js/src/Keyring.js
@@ -45,7 +45,7 @@ export class GPGME_Keyring {
      * information can be updated with the {@link Key.refresh} method.
      * @param {Boolean} options.search (optional) retrieve Keys from external
      * servers with the method(s) defined in gnupg (e.g. WKD/HKP lookup)
-     * @returns {Promise<Array<GPGME_Key>>}
+     * @returns {Promise<GPGME_Key[]>}
      * @static
      * @async
      */
@@ -138,7 +138,7 @@ export class GPGME_Keyring {
      * search for
      * @param {Boolean} options.with_secret_fpr also return a list of
      * fingerprints for the keys that have a secret key available
-     * @returns {Promise<exportResult|GPGME_Error>} Object containing the
+     * @returns {Promise<exportResult>} Object containing the
      * armored Key(s) and additional information.
      * @static
      * @async
@@ -175,7 +175,7 @@ export class GPGME_Keyring {
      * It looks up the gpg configuration if set, or the first key that
      * contains a secret key.
      *
-     * @returns {Promise<GPGME_Key|GPGME_Error>}
+     * @returns {Promise<GPGME_Key>}
      * @async
      * @static
      */
@@ -360,10 +360,10 @@ export class GPGME_Keyring {
     }
 
     /**
-     * Convenience function for deleting a Key. See {@link Key.delete} for
+     * Convenience function for deleting a Key. See {@link Key#delete} for
      * further information about the return values.
      * @param {String} fingerprint
-     * @returns {Promise<Boolean|GPGME_Error>}
+     * @returns {Promise<Boolean>}
      * @async
      * @static
      */
diff --git a/lang/js/src/Message.js b/lang/js/src/Message.js
index fff20fbe..9f6abb75 100644
--- a/lang/js/src/Message.js
+++ b/lang/js/src/Message.js
@@ -45,9 +45,10 @@ export function createMessage (operation){
 /**
  * A Message collects, validates and handles all information required to
  * successfully establish a meaningful communication with gpgme-json via
- * {@link Connection.post}. The definition on which communication is available
- * can be found in {@link permittedOperations}.
+ * [Connection.post]{@link Connection#post}. The definition on which
+ * communication is available can be found in {@link permittedOperations}.
  * @class
+ * @protected
  */
 export class GPGME_Message {
 
@@ -73,7 +74,7 @@ export class GPGME_Message {
         return this._expected;
     }
     /**
-     * The maximum size of responses from gpgme in bytes. As of July 2018,
+     * The maximum size of responses from gpgme in bytes. As of September 2018,
      * most browsers will only accept answers up to 1 MB of size.
      * Everything above that threshold will not pass through
      * nativeMessaging; answers that are larger need to be sent in parts.
@@ -96,7 +97,8 @@ export class GPGME_Message {
     }
 
     /**
-     * Returns the prepared message with parameters and completeness checked
+     * Returns the prepared message after their parameters and the completion
+     * of required parameters have been checked.
      * @returns {Object|null} Object to be posted to gnupg, or null if
      * incomplete
      */
@@ -110,10 +112,11 @@ export class GPGME_Message {
 
     /**
      * Sets a parameter for the message. It validates with
-     *      {@link permittedOperations}
+     * {@link permittedOperations}
      * @param {String} param Parameter to set
      * @param {any} value Value to set
-     * @returns {Boolean} If the parameter was set successfully
+     * @returns {Boolean} True if the parameter was set successfully.
+     * Throws errors if the parameters don't match the message operation
      */
     setParameter ( param,value ){
         if (!param || typeof (param) !== 'string'){
@@ -213,9 +216,10 @@ export class GPGME_Message {
         }
         return true;
     }
+
     /**
      * Sends the Message via nativeMessaging and resolves with the answer.
-     * @returns {Promise<Object|GPGME_Error>}
+     * @returns {Promise<Object>} GPGME response
      * @async
      */
     post (){
diff --git a/lang/js/src/Signature.js b/lang/js/src/Signature.js
index 530590f9..7f24f320 100644
--- a/lang/js/src/Signature.js
+++ b/lang/js/src/Signature.js
@@ -29,6 +29,7 @@ import { gpgme_error } from './Errors';
  * of the expected values are to be found in {@link expKeys}, {@link expSum},
  * {@link expNote}.
  * @returns {GPGME_Signature|GPGME_Error} Signature Object
+ * @private
  */
 export function createSignature (sigObject){
     if (
@@ -131,10 +132,9 @@ class GPGME_Signature {
     }
 
     /**
-     * gives more information on non-valid signatures. Refer to the gpgme
-     * docs https://www.gnupg.org/documentation/manuals/gpgme/Verify.html
+     * Object with boolean properties giving more information on non-valid
+     * signatures. Refer to the [gpgme docs]{@link https://www.gnupg.org/documentation/manuals/gpgme/Verify.html}
      * for details on the values.
-     * @returns {Object} Object with boolean properties
      */
     get errorDetails (){
         let properties = ['revoked', 'key-expired', 'sig-expired',
@@ -151,7 +151,8 @@ class GPGME_Signature {
 }
 
 /**
- * Keys and their value's type for the signature Object
+ * Expected keys and their value's type for the signature Object
+ * @private
  */
 const expKeys = {
     'wrong_key_usage': 'boolean',
@@ -175,6 +176,7 @@ const expKeys = {
 
 /**
  * Keys and their value's type for the summary
+ * @private
  */
 const expSum = {
     'valid': 'boolean',
@@ -193,6 +195,7 @@ const expSum = {
 
 /**
  * Keys and their value's type for notations objects
+ * @private
  */
 const expNote = {
     'human_readable': 'boolean',
diff --git a/lang/js/src/gpgmejs.js b/lang/js/src/gpgmejs.js
index 7b835ac2..91057242 100644
--- a/lang/js/src/gpgmejs.js
+++ b/lang/js/src/gpgmejs.js
@@ -30,16 +30,16 @@ import { createSignature } from './Signature';
 
 /**
  * @typedef {Object} decrypt_result
- * @property {String|Uint8Array} data The decrypted data
+ * @property {String|Uint8Array} data The decrypted data.
  * @property {String} format Indicating how the data was converted after being
- * received from gpgme.
+ * received from gpgme:
+ * <pre>
  *      'ascii': Data was ascii-encoded and no further processed
  *      'string': Data was decoded into an utf-8 string,
  *      'base64': Data was not processed and is a base64 string
  *      'uint8': data was turned into a Uint8Array
- *
- * @property {Boolean} is_mime (optional) the data claims to be a MIME
- * object.
+ * </pre>
+ * @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
@@ -47,22 +47,29 @@ import { createSignature } from './Signature';
 
 /**
  * @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
+ * @property {Boolean} all_valid Quick summary. True if all signatures are
+ * fully valid according to gnupg.
+ * @property {Number} count Number of signatures parsed.
+ * @property {Number} failures Number of signatures not passing as valid. This
+ * may imply bad signatures, or signatures with e.g. the public Key not being
+ * available.
+ * @property {GPGME_Signature[]} signatures.good Array of all signatures
+ * considered valid.
+ * @property {GPGME_Signature[]} signatures.bad All invalid signatures.
  */
 
 /**
- * @typedef {Object} encrypt_result The result of an encrypt operation
- * @property {String} data The encrypted message
+ * @typedef {Object} encrypt_result The result of an encrypt operation,
+ * containing the encrypted data and some additional information.
+ * @property {String} data The encrypted message.
  * @property {String} format Indicating how the data was converted after being
  *  received from gpgme.
+ * <pre>
  *      'ascii': Data was ascii-encoded and no further processed
  *      'string': Data was decoded into an utf-8 string,
  *      'base64': Data was not processed and is a base64 string
  *      'uint8': Data was turned into a Uint8Array
+ * </pre>
  */
 
 /**
@@ -77,7 +84,8 @@ import { createSignature } from './Signature';
  * @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)
+ * @property {String} signature The detached signature (only present in in
+ * detached mode)
  */
 
 /** @typedef {Object} verifyResult The result of a verification
@@ -98,17 +106,15 @@ export class GpgME {
         this._Keyring = null;
     }
 
-    /**
-     * setter for {@link setKeyring}.
-     * @param {GPGME_Keyring} keyring A Keyring to use
-     */
     set Keyring (keyring){
         if (keyring && keyring instanceof GPGME_Keyring){
             this._Keyring = keyring;
         }
     }
+
     /**
-     * Accesses the {@link GPGME_Keyring}.
+     * Accesses the {@link GPGME_Keyring}. From the Keyring, all Keys can be
+     * accessed.
      */
     get Keyring (){
         if (!this._Keyring){
@@ -118,27 +124,29 @@ export class GpgME {
     }
 
     /**
-     * Encrypt (and optionally sign) data
+     * Encrypt data for the recipients specified in publicKeys. If privateKeys
+     * are submitted, the data will be signed by those Keys.
      * @param {Object} options
      * @param {String|Object} options.data text/data to be encrypted as String.
-     * Also accepts Objects with a getText method
+     * Also accepts Objects with a getText method.
      * @param {inputKeys} options.publicKeys
      * Keys used to encrypt the message
-     * @param {inputKeys} opions.secretKeys (optional) Keys used to sign the
+     * @param {inputKeys} options.secretKeys (optional) Keys used to sign the
      * message. If Keys are present, the  operation requested is assumed
      * to be 'encrypt and sign'
-     * @param {Boolean} options.base64 (optional) The data will be interpreted
-     * as base64 encoded data.
-     * @param {Boolean} options.armor (optional) Request the output as armored
-     * block.
-     * @param {Boolean} options.wildcard (optional) If true, recipient
-     * information will not be added to the message.
-     * @param {Boolean} always_trust (optional, default true) This assumes that
-     * used keys are fully trusted. If set to false, encryption to a key not
-     * fully trusted in gnupg will fail
-     * @param {String} expect in case of armored:false, request how to return
-     * the  binary result. Accepts 'base64' or 'uint8', defaults to 'base64'.
-     * @param {Object} additional use additional valid gpg options as
+     * @param {Boolean} options.base64 (optional, default: false) The data will
+     * be interpreted as base64 encoded data.
+     * @param {Boolean} options.armor (optional, default: true) Request the
+     * output as armored block.
+     * @param {Boolean} options.wildcard (optional, default: false) If true,
+     * recipient information will not be added to the message.
+     * @param {Boolean} options.always_trust (optional, default true) This
+     * assumes that used keys are fully trusted. If set to false, encryption to
+     * a key not fully trusted in gnupg will fail.
+     * @param {String} options.expect (default: 'base64') In case of
+     * armored:false, request how to return the binary result.
+     * Accepts 'base64' or 'uint8'
+     * @param {Object} options.additional use additional valid gpg options as
      * defined in {@link permittedOperations}
      * @returns {Promise<encrypt_result>} Object containing the encrypted
      * message and additional info.
@@ -206,15 +214,21 @@ export class GpgME {
     }
 
     /**
-    * Decrypts a Message
+    * Decrypts (and verifies, if applicable) a message.
     * @param {Object} options
     * @param {String|Object} options.data text/data to be decrypted. Accepts
-    * Strings and Objects with a getText method
-    * @param {Boolean} options.base64 (optional) false if the data is an
-    * armored block, true if it is base64 encoded binary data
-    * @param {String} options.expect (optional) can be set to 'uint8' or
-    * 'base64'. Does no extra decoding on the data, and returns the decoded
-    * data as either Uint8Array or unprocessed(base64 encoded) string.
+    * Strings and Objects with a getText method.
+    * @param {Boolean} options.base64 (optional, default: false). Indicate that
+    * the input given is base64-encoded binary instead of an armored block in
+    * gpg armored form.
+    * @param {String} options.expect (optional). By default, the output is
+    * expected to be a string compatible with javascript. In cases of binary
+    * data the decryption may fail due to encoding problems. For data expected
+    * to return as binary data, the decroding after decryption can be bypassed:
+    * <pre>
+    *   'uint8': Return as Uint8Array
+    *   'base64': Return as unprocessed (base64 encoded) string.
+    * </pre>
     * @returns {Promise<decrypt_result>} Decrypted Message and information
     * @async
     */
@@ -269,14 +283,16 @@ export class GpgME {
     }
 
     /**
-     * Sign a Message
+     * Sign a Message.
      * @param {Object} options Signing options
      * @param {String|Object} options.data text/data to be signed. Accepts
      * Strings and Objects with a getText method.
      * @param {inputKeys} options.keys The key/keys to use for signing
      * @param {String} options.mode The signing mode. Currently supported:
-     *  'clearsign':The Message is embedded into the signature;
-     *  'detached': The signature is stored separately
+     * <pre>
+     *      'clearsign':The Message is embedded into the signature;
+     *      'detached': The signature is stored separately
+     * </pre>
      * @param {Boolean} options.base64 input is considered base64
      * @returns {Promise<signResult>}
      * @async
@@ -415,6 +431,7 @@ function putData (message, data){
  * Parses, validates and converts incoming objects into signatures.
  * @param {Array<Object>} sigs
  * @returns {signatureDetails} Details about the signatures
+ * @private
  */
 function collectSignatures (sigs){
     if (!Array.isArray(sigs)){
diff --git a/lang/js/src/index.js b/lang/js/src/index.js
index cf6e2d03..c52460cc 100644
--- a/lang/js/src/index.js
+++ b/lang/js/src/index.js
@@ -27,9 +27,11 @@ import { gpgme_error } from './Errors';
 import { Connection } from './Connection';
 
 /**
- * Initializes gpgme.js by testing the nativeMessaging connection once.
- * @returns {Promise<GpgME> | GPGME_Error}
- *
+ * Main entry point for gpgme.js. It initializes by testing the nativeMessaging
+ * connection once, and then offers the available functions as method of the
+ * response object.
+ * An unsuccessful attempt will reject as a GPGME_Error.
+ * @returns {Promise<GpgME>}
  * @async
  */
 function init (){