Update comments to match upstream.

Author: dmitrizagidulin

lib/index.js

@@ -5,7 +5,7 @@
  * @author David I. Lehn
  *
  * @license BSD 3-Clause License
- * Copyright (c) 2017-2021 Digital Bazaar, Inc.
+ * Copyright (c) 2017-2022 Digital Bazaar, Inc.
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -53,6 +53,26 @@ const dateRegex = new RegExp('^(\\d{4})-(0[1-9]|1[0-2])-' +
   '(\\.[0-9]+)?(Z|(\\+|-)([01][0-9]|2[0-3]):' +
   '([0-5][0-9]))$', 'i');
 
+/**
+ * @typedef {object} LinkedDataSignature
+ */
+
+/**
+ * @typedef {object} Presentation
+ */
+
+/**
+ * @typedef {object} ProofPurpose
+ */
+
+/**
+ * @typedef {object} VerifiableCredential
+ */
+
+/**
+ * @typedef {object} VerifiablePresentation
+ */
+
 module.exports = {
   issue,
   createPresentation,
@@ -93,8 +113,8 @@ module.exports = {
  * @param {LinkedDataSignature} options.suite - Signature suite (with private
  *   key material), passed in to sign().
  *
- * Either pass in a ProofPurpose, or a default one will be created:
- * @param {ProofPurpose} [options.purpose]
+ * @param {ProofPurpose} [options.purpose] - A ProofPurpose. If not specified,
+ *   a default purpose will be created.
  *
  * Other optional params passed to `sign()`:
  * @param {object} [options.documentLoader] - A document loader.
@@ -107,11 +127,11 @@ module.exports = {
  * @returns {Promise<VerifiableCredential>} Resolves on completion.
  */
 async function issue({
-                       credential, suite, expansionMap,
-                       purpose = new CredentialIssuancePurpose(),
-                       documentLoader = defaultDocumentLoader,
-                       now = new Date().toISOString()
-                     } = {}) {
+  credential, suite, expansionMap,
+  purpose = new CredentialIssuancePurpose(),
+  documentLoader = defaultDocumentLoader,
+  now
+} = {}) {
   // check to make sure the `suite` has required params
   // Note: verificationMethod defaults to publicKey.id, in suite constructor
   if(!suite) {
@@ -149,8 +169,8 @@ async function issue({
  *   presentation, signed or unsigned, that may contain within it a
  *   verifiable credential.
  *
- * @param {LinkedDataSignature|LinkedDataSignature[]} suite - One or more
- *   signature suites that are supported by the caller's use case. This is
+ * @param {LinkedDataSignature|LinkedDataSignature[]} options.suite - One or
+ *   more signature suites that are supported by the caller's use case. This is
  *   an explicit design decision -- the calling code must specify which
  *   signature types (ed25519, RSA, etc) are allowed.
  *   Although it is expected that the secure resolution/fetching of the public
@@ -168,11 +188,12 @@ async function issue({
  *
  * or a default purpose will be created with params:
  * @param {string} [options.challenge] - Required if purpose is not passed in.
- * @param {string} [options.controller]
- * @param {string} [options.domain]
+ * @param {string} [options.controller] - Purpose controller.
+ * @param {string} [options.domain] - Purpose domain.
  *
- * @param {Function} [options.documentLoader]
- * @param {Function} [options.checkStatus]
+ * @param {Function} [options.documentLoader] - Document loader function.
+ * @param {Function} [options.checkStatus] - Optional function for checking
+ *   credential status if `credentialStatus` is present on the credential.
  * @param {string|Date} [options.now] - A string representing date time in
  *   ISO 8601 format or an instance of Date. Defaults to current date time.
  *
@@ -205,8 +226,8 @@ async function verify(options = {}) {
  *
  * @param {object} options.credential - Verifiable credential.
  *
- * @param {LinkedDataSignature|LinkedDataSignature[]} suite - One or more
- *   signature suites that are supported by the caller's use case. This is
+ * @param {LinkedDataSignature|LinkedDataSignature[]} options.suite - One or
+ *   more signature suites that are supported by the caller's use case. This is
  *   an explicit design decision -- the calling code must specify which
  *   signature types (ed25519, RSA, etc) are allowed.
  *   Although it is expected that the secure resolution/fetching of the public
@@ -215,7 +236,7 @@ async function verify(options = {}) {
  *
  * @param {CredentialIssuancePurpose} [options.purpose] - Optional
  *   proof purpose (a default one will be created if not passed in).
- * @param {Function} [options.documentLoader]
+ * @param {Function} [options.documentLoader] - Document loader function.
  * @param {Function} [options.checkStatus] - Optional function for checking
  *   credential status if `credentialStatus` is present on the credential.
  * @param {string|Date} [options.now] - A string representing date time in
@@ -244,7 +265,7 @@ async function verifyCredential(options = {}) {
  * Verifies a verifiable credential.
  *
  * @private
- * @param {object} [options={}]
+ * @param {object} [options={}] - Options hashmap.
  *
  * @param {object} options.credential - Verifiable credential.
  * @param {LinkedDataSignature|LinkedDataSignature[]} options.suite - See the
@@ -254,8 +275,8 @@ async function verifyCredential(options = {}) {
  *
  * @throws {Error} If required parameters are missing (in `_checkCredential`).
  *
- * @param {CredentialIssuancePurpose} [options.purpose]
- * @param {Function} [options.documentLoader]
+ * @param {CredentialIssuancePurpose} [options.purpose] - Issuance purpose.
+ * @param {Function} [options.documentLoader] - Document loader function.
  * @param {Function} [options.checkStatus] - Optional function for checking
  *   credential status if `credentialStatus` is present on the credential.
  *
@@ -348,15 +369,16 @@ function createPresentation({verifiableCredential, id, holder, now} = {}) {
  * @param {object} [options={}] - Options to use.
  *
  * Required:
- * @param {Presentation} options.presentation
+ * @param {Presentation} options.presentation - Presentation to sign.
  * @param {LinkedDataSignature} options.suite - passed in to sign()
  *
  * Either pass in a ProofPurpose, or a default one will be created with params:
- * @param {ProofPurpose} [options.purpose]
- * @param {string} [options.domain]
- * @param {string} options.challenge - Required.
+ * @param {ProofPurpose} [options.purpose] - A ProofPurpose. If not specified,
+ *   a default purpose will be created with the domain and challenge options.
+ * @param {string} [options.domain] - Optional purpose domain.
+ * @param {string} options.challenge - Required challenge.
  *
- * @param {Function} [options.documentLoader]
+ * @param {Function} [options.documentLoader] - Document loader function.
  *
  * @returns {Promise<{VerifiablePresentation}>} A VerifiablePresentation with
  *   a proof.
@@ -378,8 +400,9 @@ async function signPresentation(options = {}) {
  * proof signature if it's present. Also verifies all the VerifiableCredentials
  * that are present in the presentation, if any.
  *
- * @param {object} [options={}]
- * @param {VerifiablePresentation} options.presentation
+ * @param {object} [options={}] - Options hashmap.
+ * @param {VerifiablePresentation} options.presentation - A
+ *   VerifiablePresentation.
  *
  * @param {LinkedDataSignature|LinkedDataSignature[]} options.suite - See the
  *   definition in the `verify()` docstring, for this param.
@@ -390,15 +413,20 @@ async function signPresentation(options = {}) {
  *   unsigned presentation.
  *
  * Either pass in a proof purpose,
- * @param {AuthenticationProofPurpose} [options.presentationPurpose]
- *
- * or a default purpose will be created with params:
- * @param {string} [options.challenge] - Required if purpose is not passed in.
- * @param {string} [options.controller]
- * @param {string} [options.domain]
- *
- * @param {Function} [options.documentLoader]
- * @param {Function} [options.checkStatus]
+ * @param {AuthenticationProofPurpose} [options.presentationPurpose] - A
+ *   ProofPurpose. If not specified, a default purpose will be created with
+ *   the challenge, controller, and domain options.
+ *
+ * @param {string} [options.challenge] - A challenge. Required if purpose is
+ *   not passed in.
+ * @param {string} [options.controller] - A controller. Required if purpose is
+ *   not passed in.
+ * @param {string} [options.domain] - A domain. Required if purpose is not
+ *   passed in.
+ *
+ * @param {Function} [options.documentLoader] - A document loader.
+ * @param {Function} [options.checkStatus] - Optional function for checking
+ *   credential status if `credentialStatus` is present on the credential.
  * @param {string|Date} [options.now] - A string representing date time in
  *   ISO 8601 format or an instance of Date. Defaults to current date time.
  *