FABN-944 JSDoc for fabric-network classes

Add outline jsdoc comments for the fabric-network API
Add fabric-network to the ‘gulp doc’ task

Change-Id: I364d642bde89d1a2739861b753588bf89691e627
Signed-off-by: andrew-coleman <andrew_coleman@uk.ibm.com>

build/tasks/doc.js

@@ -25,6 +25,8 @@ gulp.task('clean', function(){
 gulp.task('doc', ['clean'], function () {
 	gulp.src([
 		'docs/index.md',
+		'fabric-network/index.js',
+		'fabric-network/lib/**/*.js',
 		'fabric-client/index.js',
 		'fabric-client/lib/**/*.js',
 		'!fabric-client/lib/protos/**',

fabric-network/README.md

@@ -0,0 +1,14 @@
+## Hyperledger Fabric Client for Node.js
+
+SDK for writing node.js applications to interact with [Hyperledger Fabric](http://hyperledger-fabric.readthedocs.io/en/latest/).
+
+This package encapsulates the APIs to connect to a Fabric network, submit transactions and perform queries against the ledger. 
+
+Two separate packages are also provided:
+1. `fabric-client`, supporting fine grain interactions with Peers and Orders of the Fabric network to install and instantiate chaincodes, send transaction invocations and perform chaincode queries.
+2. `fabric-ca-client`, to interact with the fabric-ca to manage user certificates.
+
+For application developer documentations, please visit [https://fabric-sdk-node.github.io/](https://fabric-sdk-node.github.io/)
+
+<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
+

fabric-network/index.js

@@ -4,7 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @module fabric-network
+ */
+
 module.exports.Gateway = require('./lib/gateway');
+module.exports.Wallet = require('./lib/api/wallet');
 module.exports.InMemoryWallet = require('./lib/impl/wallet/inmemorywallet');
 module.exports.X509WalletMixin = require('./lib/impl/wallet/x509walletmixin');
 module.exports.FileSystemWallet = require('./lib/impl/wallet/filesystemwallet');

fabric-network/lib/api/queryhandler.js

@@ -6,6 +6,11 @@
 
 'use strict';
 
+/**
+ * QueryHandler defines the interface for pluggable query handlers.
+ *
+ * @interface
+ */
 class QueryHandler {
 
 	constructor(channel, mspId, peerMap, queryOptions) {

fabric-network/lib/api/wallet.js

@@ -8,7 +8,12 @@
 
 'use strict';
 
-/* eslint-disable no-unused-vars */
+/**
+ * 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
+ */
 class Wallet {
 
 	// ===============================================
@@ -27,22 +32,47 @@ class Wallet {
 	// End user APIs
 	//=========================================================
 
+	/**
+	 * Import an identity into the wallet
+	 * @param label
+	 * @param identity
+	 * @returns {Promise<void>}
+	 */
 	async import(label, identity) {
 		throw new Error('Not implemented');
 	}
 
+	/**
+	 * Extract an identity from the wallet
+	 * @param label
+	 * @returns {Promise<void>}
+	 */
 	async export(label) {
 		throw new Error('Not implemented');
 	}
 
+	/**
+	 * List the contents of the wallet
+	 * @returns {Promise<void>}
+	 */
 	async list() {
 		throw new Error('Not implemented');
 	}
 
+	/**
+	 * Removes an identity from the wallet
+	 * @param label
+	 * @returns {Promise<void>}
+	 */
 	async delete(label) {
 		throw new Error('Not implemented');
 	}
 
+	/**
+	 * Query the existence of an identity in the wallet
+	 * @param label
+	 * @returns {Promise<void>}
+	 */
 	async exists(label) {
 		throw new Error('Not implemented');
 	}

fabric-network/lib/contract.js

@@ -9,6 +9,11 @@
 const logger = require('./logger').getLogger('Contract');
 const util = require('util');
 
+/**
+ * Represents a smart contract (chaincode) instance in a network.
+ * Applications should get a Contract instance using the
+ * networks's [getContract]{@link Network#getContract} method.
+ */
 class Contract {
 
 	constructor(channel, chaincodeId, gateway, queryHandler, eventHandlerFactory) {
@@ -72,10 +77,12 @@ class Contract {
 	}
 
 	/**
-	 * Submit a transaction to the contract.
+	 * Submit a transaction to the ledger.  The transaction function <code>transactionName</code>
+	 * will be executed on the endorsing peers and then submitted to the ordering service
+	 * for committing to the ledger.
      * @param {string} transactionName Transaction function name
      * @param {...string} parameters Transaction function parameters
-     * @returns {Buffer} Payload response
+     * @returns {Buffer} Payload response from the transaction function
      */
 	async submitTransaction(transactionName, ...parameters) {
 		logger.debug('in submitTransaction: ' + transactionName);
@@ -175,9 +182,14 @@ class Contract {
 	}
 
 	/**
-     * @param {string} transactionName transaction name
-     * @param {string[]} parameters transaction parameters
-     * @returns {byte[]} payload response
+	 * Execute a transaction function and return its results.
+	 * The transaction function <code>transactionName</code>
+	 * will be executed on the endorsing peers but the responses will not be sent to to
+	 * the ordering service and hence will not be committed to the ledger.
+	 * This is used for querying the world state.
+     * @param {string} transactionName Transaction function name
+     * @param {...string} parameters Transaction function parameters
+     * @returns {Buffer} Payload response from the transaction function
      */
 	async executeTransaction(transactionName, ...parameters) {
 		this._verifyTransactionDetails('executeTransaction', transactionName, parameters);

fabric-network/lib/gateway.js

@@ -13,6 +13,17 @@ const EventStrategies = require('fabric-network/lib/impl/event/defaulteventhandl
 
 const logger = require('./logger').getLogger('Gateway');
 
+/**
+ * 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
+ * which in turn can access the [smart contracts]{@link Contract} installed on a network and
+ * [submit transactions]{@link Contract#submitTransaction} to the ledger.
+ *
+ * @class
+ */
 class Gateway {
 
 	static _mergeOptions(defaultOptions, suppliedOptions) {
@@ -60,20 +71,29 @@ class Gateway {
  	 */
 
 	/**
-	 * @typedef {Object} DefaultEventHanderOptions
+	 * @typedef {Object} DefaultEventHandlerOptions
  	 * @property {number} [commitTimeout = 300] The timeout period in seconds to wait for commit notification to complete
-	 * @property {*} [strategy] Event handling strategy to identify successful transaction commits. A null value
-	 * indicates that no event handling is desired.
+	 * @property {MSPID_SCOPE_ALLFORTX|MSPID_SCOPE_ANYFORTX|NETWORK_SCOPE_ALLFORTX|NETWORK_SCOPE_ANYFORTX} [strategy] 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}.
 	 */
 
 	/**
      * Connect to the Gateway with a connection profile or a prebuilt Client instance.
      *
-     * @param {Client | string} config The configuration for this Gateway which can come from a common connection
+     * @param {string|Client} config The configuration for this Gateway which can come from a common connection
 	 * profile or an existing fabric-client Client instance
-	 * @see see {Client}
      * @param {GatewayOptions} options specific options for creating this Gateway instance
      * @memberof Gateway
+	 * @example
+	 * const gateway = new Gateway();
+	 * const wallet = new FileSystemWallet('./WALLETS/wallet');
+	 * const ccpFile = fs.readFileSync('./network.json');
+	 * const ccp = JSON.parse(ccpFile.toString());
+	 * await gateway.connect(ccp, {
+	 *   identity: 'admin',
+	 *   wallet: wallet
+	 * });
      */
 	async connect(config, options) {
 		const method = 'connect';
@@ -129,7 +149,7 @@ class Gateway {
 	/**
      * Get the current identity
      *
-     * @returns {User} a fabric-client User instance of the current identity used by this Gateway
+     * @returns {User} A fabric-client {@link User} instance of the current identity used by this Gateway
      * @memberof Gateway
      */
 	getCurrentIdentity() {
@@ -140,7 +160,7 @@ class Gateway {
 	/**
      * Get the underlying Client object instance
      *
-     * @returns {Client} the underlying fabric-client Client instance
+     * @returns {Client} The underlying fabric-client {@link Client} instance
      * @memberof Gateway
      */
 	getClient() {
@@ -150,7 +170,7 @@ class Gateway {
 
 	/**
 	 * Returns the set of options associated with the Gateway connection
-	 * @returns {GatewayOptions} the Gateway options
+	 * @returns {GatewayOptions} The Gateway connection options
 	 * @memberof Gateway
 	 */
 	getOptions() {
@@ -159,7 +179,7 @@ class Gateway {
 	}
 
 	/**
-     * clean up and disconnect this Gateway in prep for it to be discarded and garbage collected
+     * Clean up and disconnect this Gateway connection in preparation for it to be discarded and garbage collected
      *
      * @memberof Gateway
      */
@@ -172,9 +192,9 @@ class Gateway {
 	}
 
 	/**
-	 * Returns an object representing the network
-	 * @param networkName
-	 * @returns {Promise<Network>}
+	 * Returns an object representing a network
+	 * @param {string} networkName The name of the network (channel name)
+	 * @returns {Network}
 	 * @memberof Gateway
 	 */
 	async getNetwork(networkName) {

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

@@ -83,7 +83,7 @@ class DefaultEventHandlerManager {
 	 * create an Tx Event handler for the specific txid
 	 *
 	 * @param {*} txid
-	 * @returns
+	 * @returns The transaction event handler
 	 * @memberof DefaultEventHandlerFactory
 	 */
 	createTxEventHandler(txid) {

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

@@ -9,22 +9,48 @@
 const AllForTxStrategy = require('fabric-network/lib/impl/event/allfortxstrategy');
 const AnyForTxStrategy = require('fabric-network/lib/impl/event/anyfortxstrategy');
 
+/**
+ * Default event handler strategy.<br>
+ * Listen to all event hubs for the connected organisation.
+ * The [submitTransaction]{@link 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).
+ */
 function MSPID_SCOPE_ALLFORTX(eventHubFactory, network, mspId) {
 	const peers = network.getPeerMap().get(mspId);
 	return new AllForTxStrategy(eventHubFactory, peers);
 }
 
+/**
+ * Event handler strategy.<br>
+ * Listen to all event hubs for the connected organisation.
+ * The [submitTransaction]{@link Contract#submitTransaction} method will wait
+ * until the first event from <b>any</b> of the event hubs that are still connected.
+ */
 function MSPID_SCOPE_ANYFORTX(eventHubFactory, network, mspId) {
 	const peers = network.getPeerMap().get(mspId);
 	return new AnyForTxStrategy(eventHubFactory, peers);
 }
 
+/**
+ * Event handler strategy.<br>
+ * Listen to all event hubs for all peers in the current network.
+ * The [submitTransaction]{@link 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).
+ */
 //eslint-disable-next-line no-unused-vars
 function NETWORK_SCOPE_ALLFORTX(eventHubFactory, network, mspId) {
 	const peers = network.getChannel().getPeers();
 	return new AllForTxStrategy(eventHubFactory, peers);
 }
 
+/**
+ * Event handler strategy.<br>
+ * Listen to all event hubs for all peers in the current network.
+ * The [submitTransaction]{@link Contract#submitTransaction} method will wait
+ * until the first event from <b>any</b> of the event hubs that are still connected.
+ */
 //eslint-disable-next-line no-unused-vars
 function NETWORK_SCOPE_ANYFORTX(eventHubFactory, network, mspId) {
 	const peers = network.getChannel().getPeers();

fabric-network/lib/impl/wallet/basewallet.js

@@ -12,6 +12,11 @@ const Wallet = require('../../api/wallet');
 const logger = require('../../logger').getLogger('BaseWallet');
 const util = require('util');
 
+/**
+ * Base class for the built-in wallet implementations.  For internal use only.
+ * @class
+ * @implements {Wallet}
+ */
 class BaseWallet extends Wallet {
 
 	constructor(walletMixin = new X509WalletMixin()) {
@@ -31,7 +36,7 @@ class BaseWallet extends Wallet {
 	 *
 	 * @param {*} client
 	 * @param {*} label
-	 * @returns
+	 * @returns The user context
 	 * @memberof Wallet
 	 */
 	async setUserContext(client, label) {

fabric-network/lib/impl/wallet/filesystemwallet.js

@@ -17,8 +17,7 @@ const logger = require('../../logger').getLogger('FileSystemWallet');
  * This class defines an implementation of an Identity wallet that persists
  * to the file system.
  *
- * @class FileSystemWallet
- * @see See {@link BaseWallet}
+ * @class
  * @extends {BaseWallet}
  */
 class FileSystemWallet extends BaseWallet {

fabric-network/lib/impl/wallet/inmemorywallet.js

@@ -16,6 +16,10 @@ const logger = require('../../logger').getLogger('InMemoryWallet');
 // label it will overwrite the existing one.
 const memoryStore = new Map();
 
+/**
+ * @class
+ * @extends {BaseWallet}
+ */
 class InMemoryWallet extends BaseWallet {
 	constructor(walletmixin) {
 		super(walletmixin);

fabric-network/lib/impl/wallet/x509walletmixin.js

@@ -8,6 +8,9 @@
 
 const logger = require('../../logger').getLogger('X509WalletMixin');
 
+/**
+ * @class
+ */
 class X509WalletMixin {
 
 	static createIdentity(mspId, certificate, privateKey) {