FABN-1002: Tidy-up fabric-network JSDoc

Change-Id: Ib9b73658ce73454599fe1d64b793840f05dab85a
Signed-off-by: Mark S. Lewis <mark_lewis@uk.ibm.com>

build/tasks/doc.js

@@ -69,7 +69,7 @@ gulp.task('docs-dev', ['docs'], () => {
 });
 
 
-gulp.task('doc', ['jsdocs'], () => {
+gulp.task('docs', ['jsdocs'], () => {
 	const relativePath = '..';
 	const packageJson = require(path.join(__dirname, '../..', 'package.json'));
 

docs/tutorials/tutorials.json

@@ -31,5 +31,5 @@
 	},
 	"transaction-commit-events" : {
 		"title": "fabric-network: How to wait for transactions to be commited to the ledger"
-	},
+	}
 }

fabric-network/index.js

@@ -5,6 +5,7 @@
  */
 
 /**
+ * Higher level API for interacting with smart contracts.
  * @module fabric-network
  */
 

fabric-network/lib/api/queryhandler.js

@@ -8,8 +8,9 @@
 
 /**
  * QueryHandler defines the interface for pluggable query handlers.
- *
+ * @private
  * @interface
+ * @memberof module:fabric-network
  */
 class QueryHandler {
 

fabric-network/lib/api/wallet.js

@@ -8,11 +8,28 @@
 
 'use strict';
 
+/**
+ * @typedef {Object} Wallet~IdentityInfo
+ * @memberof module:fabric-network
+ * @property label
+ * @property mspId
+ * @property identifier
+ */
+
+/**
+ * @typedef {Object} Wallet~Identity
+ * @memberof module:fabric-network
+ * @property type
+ * @property mspId
+ * @property certificate
+ * @property privateKey
+ */
+
 /**
  * Wallet defines the interface for storing and managing users' identities in a fabric network.
  * This is an abstract base class and must be extended.
- *
  * @interface
+ * @memberof module:fabric-network
  */
 class Wallet {
 
@@ -34,44 +51,47 @@ class Wallet {
 
 	/**
 	 * Import an identity into the wallet
-	 * @param label
-	 * @param identity
-	 * @returns {Promise<void>}
+	 * @async
+	 * @param {string} label
+	 * @param {module:fabric-network.Wallet~Identity} identity
 	 */
 	async import(label, identity) {
 		throw new Error('Not implemented');
 	}
 
 	/**
 	 * Extract an identity from the wallet
-	 * @param label
-	 * @returns {Promise<void>}
+	 * @async
+	 * @param {string} label
+	 * @returns {module:fabric-network.Wallet~Identity}
 	 */
 	async export(label) {
 		throw new Error('Not implemented');
 	}
 
 	/**
 	 * List the contents of the wallet
-	 * @returns {Promise<void>}
+	 * @async
+	 * @returns {module:fabric-network.Wallet~IdentityInfo[]}
 	 */
 	async list() {
 		throw new Error('Not implemented');
 	}
 
 	/**
 	 * Removes an identity from the wallet
-	 * @param label
-	 * @returns {Promise<void>}
+	 * @async
+	 * @param {string} label
 	 */
 	async delete(label) {
 		throw new Error('Not implemented');
 	}
 
 	/**
 	 * Query the existence of an identity in the wallet
-	 * @param label
-	 * @returns {Promise<void>}
+	 * @async
+	 * @param {string} label
+	 * @returns {boolean}
 	 */
 	async exists(label) {
 		throw new Error('Not implemented');

fabric-network/lib/contract.js

@@ -42,10 +42,11 @@ function verifyNamespace(namespace) {
 /**
  * Represents a smart contract (chaincode) instance in a network.
  * Applications should get a Contract instance using the
- * networks's [getContract]{@link Network#getContract} method.
+ * networks's [getContract]{@link fabric-network.Network#getContract} method.
+ * @memberof module:fabric-network
+ * @hideconstructor
  */
 class Contract {
-
 	constructor(network, chaincodeId, gateway, queryHandler, namespace) {
 		logger.debug('in Contract constructor');
 
@@ -71,7 +72,7 @@ class Contract {
 	/**
 	 * Create a new transaction ID.
 	 * @private
-	 * @returns {TransactionID} Transaction ID.
+	 * @returns {module:fabric-client.TransactionID} Transaction ID.
 	 */
 	createTransactionID() {
 		return this.gateway.getClient().newTransactionID();
@@ -98,7 +99,7 @@ class Contract {
 	/**
 	 * Get the query handler for this contract. Used by transaction evaluate.
 	 * @private
-	 * @returns {QueryHandler} A query handler.
+	 * @returns {module:fabric-network.QueryHandler} A query handler.
 	 */
 	getQueryHandler() {
 		return this.queryHandler;
@@ -110,7 +111,7 @@ class Contract {
 	 * the transaction invocation. A new transaction object <strong>must</strong>
 	 * be created for each transaction invocation.
      * @param {String} name Transaction function name.
-	 * @returns {Transaction} A transaction object.
+	 * @returns {module:fabric-network.Transaction} A transaction object.
      */
 	createTransaction(name) {
 		verifyTransactionName(name);

fabric-network/lib/gateway.js

@@ -13,16 +13,55 @@ const EventStrategies = require('fabric-network/lib/impl/event/defaulteventhandl
 
 const logger = require('./logger').getLogger('Gateway');
 
+/**
+ * @typedef {Object} Gateway~GatewayOptions
+ * @memberof module:fabric-network
+ * @property {fabric-network.Wallet} wallet The identity wallet implementation for use with this Gateway instance.
+ * @property {string} identity The identity in the wallet for all interactions on this Gateway instance.
+ * @property {string} [clientTlsIdentity] The identity in the wallet to use as the client TLS identity.
+ * @property {module:fabric-network.Gateway~DefaultEventHandlerOptions} [eventHandlerOptions] Options for the inbuilt default
+ * event handler capability.
+ */
+
+/**
+ * @typedef {Object} Gateway~DefaultEventHandlerOptions
+ * @memberof module:fabric-network
+ * @property {number} [commitTimeout = 300] The timeout period in seconds to wait for commit notification to
+ * complete.
+ * @property {?module:fabric-network.Gateway~TxEventHandlerFactory} [strategy = MSPID_SCOPE_ALLFORTX] Event handling strategy to identify
+ * successful transaction commits. A null value indicates that no event handling is desired. The default is
+ * {@link MSPID_SCOPE_ALLFORTX}.
+ */
+
+/**
+ * @typedef {Function} Gateway~TxEventHandlerFactory
+ * @memberof module:fabric-network
+ * @param {String} transactionId The transaction ID for which the handler should listen.
+ * @param {module:fabric-network.Network} network The network on which this transaction is being submitted.
+ * @returns {module:fabric-network.Gateway~TxEventHandler} A transaction event handler.
+ */
+
+/**
+ * @typedef {Object} Gateway~TxEventHandler
+ * @memberof module:fabric-network
+ * @property {Function} startLstening Async function that resolves when the handler has started listening for
+ * transaction commit events. Called after the transaction proposal has been accepted and prior to submission of
+ * the transaction to the orderer.
+ * @property {Function} waitForEvents Async function that resolves (or rejects) when suitable transaction
+ * commit events have been received. Called after submission of the transaction to the orderer.
+ * @property {Function} cancelListening Cancel listening. Called if submission of the transaction to the orderer
+ * fails.
+ */
+
 /**
  * The gateway peer provides the connection point for an application to access the Fabric network.  It is instantiated using
  * the default constructor.
- * It can then be connected to a fabric network using the [connect]{@link Gateway#connect} method by passing either a CCP definition
- * or an existing {@link Client} object.
- * Once connected, it can then access individual Network instances (channels) using the [getNetwork]{@link Gateway#getNetwork} method
+ * It can then be connected to a fabric network using the [connect]{@link #connect} method by passing either a CCP definition
+ * or an existing {@link module:fabric-client.Client} object.
+ * Once connected, it can then access individual Network instances (channels) using the [getNetwork]{@link #getNetwork} method
  * which in turn can access the [smart contracts]{@link Contract} installed on a network and
  * [submit transactions]{@link Contract#submitTransaction} to the ledger.
- *
- * @class
+ * @memberof module:fabric-network
  */
 class Gateway {
 
@@ -40,9 +79,6 @@ class Gateway {
 		}
 	}
 
-	/**
-	 * Public constructor for Gateway object
-	 */
 	constructor() {
 		logger.debug('in Gateway constructor');
 		this.client = null;
@@ -65,49 +101,16 @@ class Gateway {
 		};
 	}
 
-	/**
- 	 * @typedef {Object} GatewayOptions
-	 * @property {Wallet} wallet The identity wallet implementation for use with this Gateway instance.
- 	 * @property {string} identity The identity in the wallet for all interactions on this Gateway instance.
-	 * @property {string} [clientTlsIdentity] the identity in the wallet to use as the client TLS identity.
-	 * @property {DefaultEventHandlerOptions} [eventHandlerOptions] This defines options for the inbuilt default
-	 * event handler capability.
- 	 */
-
-	/**
-	 * @typedef {Object} DefaultEventHandlerOptions
- 	 * @property {number} [commitTimeout = 300] The timeout period in seconds to wait for commit notification to
-	 * complete.
-	 * @property {?TxEventHandlerFactory} [strategy = MSPID_SCOPE_ALLFORTX] Event handling strategy to identify
-	 * successful transaction commits. A null value indicates that no event handling is desired. The default is
-	 * {@link MSPID_SCOPE_ALLFORTX}.
-	 */
-
-	/**
-	 * @typedef {Function} TxEventHandlerFactory
-	 * @param {String} transactionId The transaction ID for which the handler should listen.
-	 * @param {Network} network The network on which this transaction is being submitted.
-	 * @returns {TxEventHandler} A transaction event handler.
-	 */
-
-	/**
-	 * @typedef {Object} TxEventHandler
-	 * @property {Function} startLstening Async function that resolves when the handler has started listening for
-	 * transaction commit events. Called after the transaction proposal has been accepted and prior to submission of
-	 * the transaction to the orderer.
-	 * @property {Function} waitForEvents Async function that resolves (or rejects) when suitable transaction
-	 * commit events have been received. Called after submission of the transaction to the orderer.
-	 * @property {Function} cancelListening Cancel listening. Called if submission of the transaction to the orderer
-	 * fails.
-	 */
-
 	/**
      * Connect to the Gateway with a connection profile or a prebuilt Client instance.
-     *
-     * @param {string|Client} config The configuration for this Gateway which can come from a common connection
-	 * profile or an existing fabric-client Client instance
-     * @param {GatewayOptions} options specific options for creating this Gateway instance
-     * @memberof Gateway
+     * @async
+     * @param {(string|object|module:fabric-client.Client)} config The configuration for this Gateway which can be:
+	 * <ul>
+	 *   <li>A fully qualified common connection profile file path (String)</li>
+	 *   <li>A common connection profile JSON (Object)</li>
+	 *   <li>A pre-configured client instance</li>
+	 * </ul>
+     * @param {module:fabric-network.Gateway~GatewayOptions} options specific options for creating this Gateway instance
 	 * @example
 	 * const gateway = new Gateway();
 	 * const wallet = new FileSystemWallet('./WALLETS/wallet');
@@ -182,8 +185,7 @@ class Gateway {
 	/**
      * Get the current identity
      *
-     * @returns {User} A fabric-client {@link User} instance of the current identity used by this Gateway
-     * @memberof Gateway
+     * @returns {module:fabric-client.User} The current identity used by this Gateway.
      */
 	getCurrentIdentity() {
 		logger.debug('in getCurrentIdentity');
@@ -193,8 +195,7 @@ class Gateway {
 	/**
      * Get the underlying Client object instance
      *
-     * @returns {Client} The underlying fabric-client {@link Client} instance
-     * @memberof Gateway
+     * @returns {module:fabric-client.Client} The underlying client instance
      */
 	getClient() {
 		logger.debug('in getClient');
@@ -203,8 +204,7 @@ class Gateway {
 
 	/**
 	 * Returns the set of options associated with the Gateway connection
-	 * @returns {GatewayOptions} The Gateway connection options
-	 * @memberof Gateway
+	 * @returns {module:fabric-network.Gateway~GatewayOptions} The Gateway connection options
 	 */
 	getOptions() {
 		logger.debug('in getOptions');
@@ -213,8 +213,6 @@ class Gateway {
 
 	/**
      * Clean up and disconnect this Gateway connection in preparation for it to be discarded and garbage collected
-     *
-     * @memberof Gateway
      */
 	disconnect() {
 		logger.debug('in disconnect');
@@ -227,8 +225,7 @@ class Gateway {
 	/**
 	 * Returns an object representing a network
 	 * @param {string} networkName The name of the network (channel name)
-	 * @returns {Network}
-	 * @memberof Gateway
+	 * @returns {module:fabric-network.Network}
 	 */
 	async getNetwork(networkName) {
 		logger.debug('in getNetwork');

fabric-network/lib/impl/event/defaulteventhandlerstrategies.js

@@ -66,6 +66,25 @@ function NETWORK_SCOPE_ANYFORTX(transactionId, network, options) {
 	return new TransactionEventHandler(transactionId, eventStrategy, options);
 }
 
+/**
+ * @typedef DefaultEventHandlerStrategies
+ * @memberof module:fabric-network
+ * @property NETWORK_SCOPE_ANYFORTX Listen to all event hubs for the connected organisation.
+ * The [submitTransaction]{@link module:fabric-network.Contract#submitTransaction} method will wait
+ * until <b>all</b> of the events to be received from
+ * all of the event hubs that are still connected (minimum 1).
+ * @property MSPID_SCOPE_ALLFORTX Listen to all event hubs for the connected organisation.
+ * The [submitTransaction]{@link module:fabric-network.Contract#submitTransaction} method will wait
+ * until the first event from <b>any</b> of the event hubs that are still connected.
+ * @property MSPID_SCOPE_ANYFORTX Listen to all event hubs for all peers in the current network.
+ * The [submitTransaction]{@link module:fabric-network.Contract#submitTransaction} method will wait
+ * until <b>all</b> of the events to be received from
+ * all of the event hubs that are still connected (minimum 1).
+ * @property NETWORK_SCOPE_ALLFORTX Listen to all event hubs for all peers in the current network.
+ * The [submitTransaction]{@link module:fabric-network.Contract#submitTransaction} method will wait
+ * until the first event from <b>any</b> of the event hubs that are still connected.
+*/
+
 module.exports = {
 	MSPID_SCOPE_ALLFORTX,
 	MSPID_SCOPE_ANYFORTX,