FABN-1506: JSDoc improvements (#170)

Signed-off-by: Mark S. Lewis <[email protected]>

fabric-network/index.js

@@ -366,9 +366,17 @@
 
 
 /**
- * A Network represents the set of peers in a Fabric network.
+ * <p>A Network represents the set of peers in a Fabric network.
  * Applications should get a Network instance using the
- * gateway's [getNetwork]{@link module:fabric-network.Gateway#getNetwork} method.
+ * gateway's [getNetwork]{@link module:fabric-network.Gateway#getNetwork} method.</p>
+ *
+ * <p>The Network object provides the ability for applications to:</p>
+ * <ul>
+ *   <li>Obtain a specific smart contract deployed to the network using [getContract]{@link module:fabric-network.Network#getContract},
+ *       in order to submit and evaluate transactions for that smart contract.</li>
+ *   <li>Listen to new block events and replay previous block events using
+ *       [addBlockListener]{@link module:fabric-network.Network#addBlockListener}.</li>
+ * </ul>
  * @interface Network
  * @memberof module:fabric-network
  */
@@ -398,7 +406,8 @@
  */
 
 /**
- * Add a listener to receive transaction commit and peer disconnect events for a set of peers.
+ * Add a listener to receive transaction commit and peer disconnect events for a set of peers. This is typically used
+ * only within the implementation of a custom [transaction commit event handler]{@tutorial transaction-commit-events}.
  * @method Network#addCommitListener
  * @memberof module:fabric-network
  * @param {module:fabric-network.CommitListener} listener A transaction commit listener callback function.

fabric-network/src/contract.js

@@ -41,9 +41,23 @@ function verifyNamespace(namespace) {
 }
 
 /**
- * Represents a smart contract (chaincode) instance in a network.
+ * <p>Represents a smart contract (chaincode) instance in a network.
  * Applications should get a Contract instance using the
- * networks's [getContract]{@link module:fabric-network.Network#getContract} method.
+ * networks's [getContract]{@link module:fabric-network.Network#getContract} method.</p>
+ *
+ * <p>The Contract allows applications to:</p>
+ * <ul>
+ *   <li>Submit transactions that store state to the ledger using
+ *       [submitTransaction]{@link module:fabric-network.Contract#submitTransaction}.</li>
+ *   <li>Evaluate transactions that query state from the ledger using
+ *       [evaluateTransaction]{@link module:fabric-network.Contract#evaluateTransaction}.</li>
+ *   <li>Listen for new events and replay previous events emitted by the smart contract using
+ *       [addContractListener]{@link module:fabric-network.Contract#addContractListener}.</li>
+ * </ul>
+ *
+ * <p>If more control over transaction invocation is required, such as including transient data,
+ * [createTransaction]{@link module:fabric-network.Contract#createTransaction} can be used to build a transaction
+ * request that is submitted to or evaluated by the smart contract.</p>
  * @memberof module:fabric-network
  * @hideconstructor
  */
@@ -118,6 +132,14 @@ class Contract {
 	 * @param {module:fabric-network.ContractListener} listener A contract listener callback function.
 	 * @param {module:fabric-network.ListenerOptions} [options] Listener options.
 	 * @returns {Promise<module:fabric-network.ContractListener>} The added listener.
+	 * @example
+	 * const listener: ContractListener = async (event) => {
+	 *     if (event.eventName ===  'newOrder') {
+	 *         const details = event.payload.toString('utf8');
+	 *         // Run business process to handle orders
+	 *     }
+	 * };
+	 * contract.addContractListener(listener);
 	 */
 	async addContractListener(listener, options) {
 		const sessionSupplier = () => new ContractListenerSession(listener, this.chaincodeId, this.network, options);