Add documentation to functions

decode.js

@@ -1,5 +1,17 @@
 var jws = require('jws');
 
+/**
+ * (Synchronous) Returns the decoded payload without verifying if the signature is valid.
+ *
+ * > Warning: This will not verify whether the signature is valid. You should not use this for untrusted messages. You most likely want to use `jwt.verify` instead.
+ *
+ * > Warning: When the token comes from an untrusted source (e.g. user input or external request), the returned decoded payload should be treated like any other user input; please make sure to sanitize and only work with properties that are expected.
+ * @param {string} jwt The JsonWebToken string.
+ * @param {object?} options Options
+ * @param {object} options.json Force `JSON.parse` on the payload even if the header doesn't contain `"typ":"JWT"`.
+ * @param {boolean} options.complete Return an object with the decoded payload and header.
+ * @returns {{header: *, payload: string, signature: *}|string|null}
+ */
 module.exports = function (jwt, options) {
   options = options || {};
   var decoded = jws.decode(jwt, options);

lib/JsonWebTokenError.js

@@ -1,3 +1,9 @@
+/**
+ * Error object
+ * @param {string} message Error message
+ * @param {Error} error Inner error
+ * @constructor
+ */
 var JsonWebTokenError = function (message, error) {
   Error.call(this, message);
   if(Error.captureStackTrace) {

lib/NotBeforeError.js

@@ -1,5 +1,11 @@
 var JsonWebTokenError = require('./JsonWebTokenError');
 
+/**
+ * Thrown if current time is before the nbf claim.
+ * @param {string} message Error message
+ * @param {Date} date Date
+ * @constructor
+ */
 var NotBeforeError = function (message, date) {
   JsonWebTokenError.call(this, message);
   this.name = 'NotBeforeError';

lib/TokenExpiredError.js

@@ -1,5 +1,11 @@
 var JsonWebTokenError = require('./JsonWebTokenError');
 
+/**
+ * Thrown error if the token is expired.
+ * @param {string} message Error message
+ * @param {Date} expiredAt Date
+ * @constructor
+ */
 var TokenExpiredError = function (message, expiredAt) {
   JsonWebTokenError.call(this, message);
   this.name = 'TokenExpiredError';

sign.js

@@ -83,6 +83,29 @@ const options_for_objects = [
   'jwtid',
 ];
 
+/**
+ * (Asynchronous) If a callback is supplied, the callback is called with the err or the JWT.
+ *
+ * (Synchronous) Returns the JsonWebToken as string
+ * @param {object | Buffer | string} payload Represents valid JSON.
+ * @param {string | Buffer | object | KeyObject} secretOrPrivateKey Contains either the secret for HMAC algorithms or the PEM encoded private key for RSA and ECDSA. In case of a private key with passphrase an object `{ key, passphrase }` can be used (based on [crypto documentation](https://nodejs.org/api/crypto.html#crypto_sign_sign_private_key_output_format)), in this case be sure you pass the `algorithm` option. When signing with RSA algorithms the minimum modulus length is 2048 except when the allowInsecureKeySizes option is set to true. Private keys below this size will be rejected with an error.
+ * @param {object?} options Options
+ * @param {string} options.algorithm (default: `HS256`)
+ * @param {string | number} options.expiresIn Expressed in seconds or a string describing a time span vercel/ms.
+ * @param {string | number} options.notBefore Expressed in seconds or a string describing a time span vercel/ms.
+ * @param options.audience
+ * @param options.issuer
+ * @param options.jwtid
+ * @param options.subject
+ * @param options.noTimestamp
+ * @param options.header
+ * @param options.keyid
+ * @param {boolean} options.mutatePayload If `true`, the sign function will modify the payload object directly. This is useful if you need a raw reference to the payload after claims have been applied to it, but before it has been encoded into a token.
+ * @param {boolean} options.allowInsecureKeySizes If `true` allows private keys with a modulus below 2048 to be used for RSA.
+ * @param {boolean} options.allowInvalidAsymmetricKeyTypes If `true`, allows asymmetric keys which do not match the specified algorithm. This option is intended only for backwards compatability and should be avoided.
+ * @param {function?} callback
+ * @returns {*}
+ */
 module.exports = function (payload, secretOrPrivateKey, options, callback) {
   if (typeof options === 'function') {
     callback = options;

verify.js

@@ -18,6 +18,31 @@ if (PS_SUPPORTED) {
   RSA_KEY_ALGS.splice(RSA_KEY_ALGS.length, 0, 'PS256', 'PS384', 'PS512');
 }
 
+/**
+ * (Asynchronous) If a callback is supplied, function acts asynchronously. The callback is called with the decoded payload if the signature is valid and optional expiration, audience, or issuer are valid. If not, it will be called with the error.
+ *
+ * (Synchronous) If a callback is not supplied, function acts synchronously. Returns the payload decoded if the signature is valid and optional expiration, audience, or issuer are valid. If not, it will throw the error.
+ *
+ * > Warning: When the token comes from an untrusted source (e.g. user input or external requests), the returned decoded payload should be treated like any other user input; please make sure to sanitize and only work with properties that are expected.
+ * @param {string} jwtString The JsonWebToken string
+ * @param {string | Buffer | KeyObject} secretOrPublicKey Contains either the secret for HMAC algorithms, or the PEM encoded public key for RSA and ECDSA. If `jwt.verify` is called asynchronous, `secretOrPublicKey` can be a function that should fetch the secret or public key.
+ * @param {object?} options Options
+ * @param {string[]} options.algorithms List of string with the names of the allowed algorithms.
+ * @param {string | string[] | RegExp} options.audience If you want to check audience (aud), provide a value here.
+ * @param {boolean} options.complete Return an object with the decoded `{ payload, header, signature }` instead of only the usual content of the payload.
+ * @param {string | string[]?} options.issuer Valid values for the iss field.
+ * @param {string?} options.jwtid If you want to check JWT ID (jti), provide a string value here.
+ * @param {boolean} options.ignoreExpiration If `true` do not validate the expiration of the token.
+ * @param options.ignoreNotBefore ...
+ * @param options.subject If you want to check subject (`sub`), provide a value here.
+ * @param {number} options.clockTolerance Number of seconds to tolerate when checking the nbf and exp claims, to deal with small clock differences among different servers.
+ * @param {string | number} options.maxAge The maximum allowed age for tokens to still be valid. It is expressed in seconds or a string describing a time span vercel/ms.
+ * @param {number} options.clockTimestamp The time in seconds that should be used as the current time for all necessary comparisons.
+ * @param {string} options.nonce If you want to check nonce claim, provide a string value here. It is used on Open ID for the ID Tokens.
+ * @param options.allowInvalidAsymmetricKeyTypes If true, allows asymmetric keys which do not match the specified algorithm. This option is intended only for backwards compatability and should be avoided.
+ * @param {function?} callback Callback function
+ * @returns {*}
+ */
 module.exports = function (jwtString, secretOrPublicKey, options, callback) {
   if ((typeof options === 'function') && !callback) {
     callback = options;