From 59d8bdc90aad88b386932f8da106d041b282385f Mon Sep 17 00:00:00 2001
From: Hayden Young <haydenyoung@wijiti.com>
Date: Mon, 19 Jun 2023 02:24:52 +0100
Subject: [PATCH] docs: Remove docblocks for Identity. Document Identity
 properties and functions.

---
 src/identities/identities.js | 19 ++++++++++++++----
 src/identities/identity.js   | 38 ++++++++++++------------------------
 2 files changed, 28 insertions(+), 29 deletions(-)

diff --git a/src/identities/identities.js b/src/identities/identities.js
index ea96511..7ceb824 100644
--- a/src/identities/identities.js
+++ b/src/identities/identities.js
@@ -67,7 +67,7 @@ const Identities = async ({ keystore, path, storage, ipfs } = {}) => {
    * Creates an identity, adding it to storage.
    * @param {Object} options Various options for configuring a new identity.
    * @param {string} [options.type=publickey] The type of provider to use for generating an identity.
-   * @return {Identity} An instance of identity.
+   * @return {module:Identities~Identity} An instance of identity.
    * @memberof module:Identities~Identities
    * @instance
    */
@@ -96,7 +96,7 @@ const Identities = async ({ keystore, path, storage, ipfs } = {}) => {
 
   /**
    * Verifies an identity using the identity's provider.
-   * @param {Identity} identity The identity to verify.
+   * @param {module:Identities~Identity} identity The identity to verify.
    * @return {boolean} True the identity is valid, false otherwise.
    * @memberof module:Identities~Identities
    */
@@ -129,10 +129,11 @@ const Identities = async ({ keystore, path, storage, ipfs } = {}) => {
 
   /**
    * Signs data using an identity.
-   * @param {Identity} identity The identity to use for signing.
+   * @param {module:Identities~Identity} identity The identity to use for
+   * signing.
    * @param {string} data The data to sign.
    * @return {string} The signed data.
-   * @throws Private signing key not fund from KeyStore when no signing key can
+   * @throws Private signing key not found from KeyStore when no signing key can
    * be retrieved.
    * @memberof module:Identities~Identities
    * @instance
@@ -147,6 +148,16 @@ const Identities = async ({ keystore, path, storage, ipfs } = {}) => {
     return await signMessage(signingKey, data)
   }
 
+  /**
+   * Verifies data using a valid signature and publicKey.
+   * @param {string} signature A signature.
+   * @param {string} publicKey A public key.
+   * @param {string} data The data to be verified.
+   * @return {boolean} True if the the data is signed by the publicKey, false
+   * otherwise.
+   * @memberof module:Identities~Identities
+   * @instance
+   */
   const verify = async (signature, publicKey, data) => {
     return await verifyMessage(signature, publicKey, data)
   }
diff --git a/src/identities/identity.js b/src/identities/identity.js
index 9ee25f5..d33377f 100644
--- a/src/identities/identity.js
+++ b/src/identities/identity.js
@@ -1,8 +1,3 @@
-/**
- * @module Identity
- * @description
- * An identity.
- */
 import * as Block from 'multiformats/block'
 import * as dagCbor from '@ipld/dag-cbor'
 import { sha256 } from 'multiformats/hashes/sha2'
@@ -12,27 +7,20 @@ const codec = dagCbor
 const hasher = sha256
 const hashStringEncoding = base58btc
 
-/**
- * Creates an instance of Identity.
- * @function
- * @param {Object} params One or more parameters for configuring an Identity.
- * @param {string} params.id A unique identitifer for the identity.
- * @param {string} params.publicKey A public key.
- * @param {Object} params.signatures A signed identity id and public key.
- * @param {string} params.type The type of identity provider.
- * @param {function} params.sign A sign function.
- * @param {function} params.verify A verify function.
- * @return {module:Identity~Identity} An instance of Identity.
- * @throws Identity id is required if id is not provided.
- * @throws Invalid public key if publicKey is not provided.
- * @throws Signatures object is required if signature is not provided.
- * @throws Signature of id is required if signature's id is not provided.
- * @throws Signature of publicKey+id is required if signature's publicKey+id is
- * not provided.
- * @throws Identity type is required if type is not provided.
- * @instance
- */
 const Identity = async ({ id, publicKey, signatures, type, sign, verify } = {}) => {
+  /**
+   * @namespace module:Identities~Identity
+   * @description The Identity instance. Returned by
+   * [Identities.createIdentity()]{@link module:Identities~Identities#createIdentity}.
+   *
+   * Available Identity instance properties and functions are:
+   * - **id:** A unique identifer for the identity.
+   * - **publicKey:** A public key.
+   * - **signatures:** A signed identity id and public key.
+   * - **type:** The type of identity provider.
+   * - **sign:** A sign function.
+   * - **verify:** A verify function.
+   */
   if (id == null) throw new Error('Identity id is required')
   if (publicKey == null) throw new Error('Invalid public key')
   if (signatures == null) throw new Error('Signatures object is required')