[FAB-4456] JSDoc cleanup and enhancement - part VI

- Config.js - Orderer.js - Peer.js Change-Id: Ib1e865a768cba1a3729e0606e681dd09358a50e3 Signed-off-by: Jim Zhang <[email protected]>
hyperledger · Jun 16, 2017 · 164b777 · 164b777
1 parent dd49adb
commit 164b777
Show file tree

Hide file tree

Showing 5 changed files with 70 additions and 128 deletions.
diff --git a/fabric-client/lib/Config.js b/fabric-client/lib/Config.js
@@ -14,31 +14,6 @@
  *  limitations under the License.
  */
 
-/**
- * This is the configuration class for the "fabric-client" package.
- * It provides all configuration settings using "config" node.js package to retrieve the
- * settings from JSON based files, environment settings, and command line startup settings
- *
- * configuration settings will be overridden in this order
- *  first files are loaded in this order
- *    $NODE_CONFIG_DIR/default.json
- *    $NODE_CONFIG_DIR/$NODE_ENV.json
- *
- *  NODE_CONFIG_DIR defaults to './config'  the configuration directory is relative to where the application is started
- *  NODE_ENV        defaults to 'development'
- *
- * then then following environment setting will override file settings
- *     $NODE_CONFIG
- *  $ export NODE_CONFIG='{"request-timeout": 3000 }'
- *
- * then the command line setting will override all
- *     node myapp.js --NODE_CONFIG='{"request-timeout": 7000 }'
- *
- *
- *   see the following for complete information on the configuration settings
- *         https://www.npmjs.com/package/config
- */
-
 'use strict';
 
 var nconf = require('nconf');
@@ -47,18 +22,9 @@ var path  = require('path');
 //
 // The class representing the hierarchy of configuration settings.
 //
-//
 
 var Config = class {
 
-	//	 Setup nconf to use (search order):
-	//	  1. in memory - all settings added with utils.setConfigSetting(name,value)
-	//	  2. Command-line arguments
-	//	  3. Environment variables (names will be change from AAA-BBB to aaa-bbb)
-	//	  4. user Files - all files added with the addConfigFile(path)
-	//	     will be ordered by when added, were last one added will override previously added files
-	//	  5. The file located at 'config/default.json' with default settings
-	//
 	constructor() {
 		nconf.use('memory');
 		nconf.argv();
@@ -82,10 +48,6 @@ var Config = class {
 			var value = settings[key];
 			key = key.toLowerCase();
 			key = key.replace(/_/g, '-');
-//			if(store.get(key)) {
-//				throw new Error('Unable to map environment variable to configuration setting.
-//				There is another config setting with the same converted name:'+key);
-//			}
 			store.set(key,value);
 		}
 	}

diff --git a/fabric-client/lib/Orderer.js b/fabric-client/lib/Orderer.js
@@ -27,23 +27,28 @@ var _abProto = grpc.load(__dirname + '/protos/orderer/ab.proto').orderer;
 var _common = grpc.load(__dirname + '/protos/common/common.proto').common;
 
 /**
- * The Orderer class represents a peer in the target blockchain network to which
- * HFC sends a block of transactions of endorsed proposals requiring ordering.
+ * The Orderer class encapsulates the client capabilities to interact with
+ * an Orderer node in the target blockchain network. The orderer node exposes
+ * two APIs: broadcast() and deliver(). Both are streaming APIs so there's
+ * a persistent grpc streaming connection between the client and the orderer
+ * where messages are exchanged in both directions. The broadcast() API is
+ * for sending transactions to the orderer for processing. The deliver() API
+ * is for asking the orderer for information such as channel configurations.
  *
  * @class
  */
 var Orderer = class extends Remote {
 
 	/**
-	 * Constructs an Orderer given its endpoint configuration settings.
+	 * Constructs an Orderer object with the given url and opts. An orderer object
+	 * encapsulates the properties of an orderer node and the interactions with it via
+	 * the grpc stream API. Orderer objects are used by the {@link Client} objects to broadcast
+	 * requests for creating and updating channels. They are also used by the {@link Channel}
+	 * objects to broadcast requests for ordering transactions.
 	 *
-	 * @param {string} url The orderer URL with format of 'grpcs://host:port'.
-	 * @param {Object} opts The options for the connection to the orderer.
-	 * <br>- request-timeout {string} A integer value in milliseconds to
-	 *       be used as node.js based timeout. This will break the request
-	 *       operation if the grpc request has not responded within this
-	 *       timeout period.
-	 *   note: other options will be passed to the grpc connection
+	 * @param {string} url The URL with format of "grpc(s)://host:port".
+	 * @param {ConnectionOpts} opts The options for the connection to the orderer.
+	 * @returns {Orderer} The Orderer instance.
 	 */
 	constructor(url, opts) {
 		super(url, opts);
@@ -52,13 +57,21 @@ var Orderer = class extends Remote {
 		this._ordererClient = new _abProto.AtomicBroadcast(this._endpoint.addr, this._endpoint.creds, this._options);
 	}
 
+	/**
+	 * @typedef {Object} BroadcastResponse
+	 * @property {string} status - Value is 'SUCCESS' or a descriptive error string
+	 */
+
 	/**
 	 * Send a Broadcast message to the orderer service.
 	 *
-	 * @param {byte} envelope - Byte data to be included in the Broadcast
-	 *        @see the ./proto/orderer/ab.proto
-	 * @returns {Promise} A Promise for a BroadcastResponse
-	 *        @see the ./proto/orderer/ab.proto
+	 * @param {byte[]} envelope - Byte data to be included in the broadcast. This must
+	 *                            be a protobuf encoded byte array of the
+	 *                            [common.Envelope]{@link https://github.com/hyperledger/fabric/blob/v1.0.0-beta/protos/common/common.proto#L132}
+	 *                            that contains either a [ConfigUpdateEnvelope]{@link https://github.com/hyperledger/fabric/blob/v1.0.0-beta/protos/common/configtx.proto#L70}
+	 *                            or a [Transaction]{@link https://github.com/hyperledger/fabric/blob/v1.0.0-beta/protos/peer/transaction.proto#L70}
+	 *                            in the <code>payload.data</code> property of the envelope.
+	 * @returns {Promise} A Promise for a {@link BroadcastResponse} object
 	 */
 	sendBroadcast(envelope) {
 		logger.debug('sendBroadcast - start');
@@ -133,10 +146,21 @@ var Orderer = class extends Remote {
 	/**
 	 * Send a Deliver message to the orderer service.
 	 *
-	 * @param {byte} envelope - Byte data to be included in the Deliver
-	 *        @see the ./proto/orderer/ab.proto
-	 * @returns {Promise} A Promise for a Block
-	 *        @see the ./proto/orderer/common.proto
+	 * @param {byte[]} envelope - Byte data to be included in the broadcast. This must
+	 *                            be a protobuf encoded byte array of the
+	 *                            [common.Envelope]{@link https://github.com/hyperledger/fabric/blob/v1.0.0-beta/protos/common/common.proto#L132}
+	 *                            that contains a [SeekInfo]{@link https://github.com/hyperledger/fabric/blob/v1.0.0-beta/protos/orderer/ab.proto#L54}
+	 *                            in the <code>payload.data</code> property of the envelope.
+	 *                            The <code>header.channelHeader.type</code> must be set to
+	 *                            [common.HeaderType.DELIVER_SEEK_INFO]{@link https://github.com/hyperledger/fabric/blob/v1.0.0-beta/protos/common/common.proto#L44}
+	 * @returns {Promise} A Promise for a protobuf object of type common.Block. Note that this
+	 *                    is <b>NOT</b> the same type of object as the {@link Block} returned by the
+	 *                    [BlockDecoder.decode()]{@link BlockDecode.decode} method and various
+	 *                    other methods. A {@link Block} is a pure javascript object, whereas
+	 *                    the object returned by this method is a protobuf object that contains
+	 *                    accessor methods, getters and setters, and toBuffer() for each property
+	 *                    to be used for further manipulating the object and convert to and from
+	 *                    byte arrays.
 	 */
 	sendDeliver(envelope) {
 		logger.debug('sendDeliver - start');

diff --git a/fabric-client/lib/Peer.js b/fabric-client/lib/Peer.js
@@ -27,35 +27,27 @@ var _serviceProto = grpc.load(__dirname + '/protos/peer/peer.proto').protos;
 var logger = utils.getLogger('Peer.js');
 
 /**
- * The Peer class represents a peer in the target blockchain network to which
- * HFC sends endorsement proposals, transaction ordering or query requests.
- *
- * The Peer class represents the remote Peer node and its network membership materials,
- * aka the ECert used to verify signatures. Peer membership represents organizations,
- * unlike User membership which represents individuals.
- *
- * When constructed, a Peer instance can be designated as an event source, in which case
- * a “eventSourceUrl” attribute should be configured. This allows the SDK to automatically
- * attach transaction event listeners to the event stream.
- *
- * It should be noted that Peer event streams function at the Peer level and not at the
- * channel and chaincode levels.
+ * The Peer class represents an endorsing peer in the target blockchain network.
+ * The application can send endorsement proposals, and query requests through this
+ * class.
  *
  * @class
  * @extends Remote
  */
 var Peer = class extends Remote {
 
 	/**
-	 * Constructs a Peer given its endpoint configuration settings.
+	 * Construct a Peer object with the given url and opts. A peer object
+	 * encapsulates the properties of an endorsing peer and the interactions with it
+	 * via the grpc service API. Peer objects are used by the {@link Client} objects to
+	 * send channel-agnostic requests such as installing chaincode, querying peers for
+	 * installed chaincodes, etc. They are also used by the {@link Channel} objects to
+	 * send channel-aware requests such as instantiating chaincodes, and invoking
+	 * transactions.
 	 *
-	 * @param {string} url The URL with format of "grpcs://host:port".
-	 * @param {Object} opts The options for the connection to the peer.
-	 * <br>- request-timeout {string} A integer value in milliseconds to
-	 *       be used as node.js based timeout. This will break the request
-	 *       operation if the grpc request has not responded within this
-	 *       timeout period.
-	 *   note: other options will be passed to the grpc connection
+	 * @param {string} url - The URL with format of "grpc(s)://host:port".
+	 * @param {ConnectionOpts} opts - The options for the connection to the peer.
+	 * @returns {Peer} The Peer instance.
 	 */
 	constructor(url, opts) {
 		super(url, opts);
@@ -66,43 +58,30 @@ var Peer = class extends Remote {
 	}
 
 	/**
-	 * Get the Peer name. Required property for the instance objects.
-	 * @returns {string} The name of the Peer
+	 * Get the Peer name. This is a client-side only identifier for this
+	 * Peer object.
+	 * @returns {string} The name of the Peer object
 	 */
 	getName() {
 		return this._name;
 	}
 
 	/**
-	 * Set the Peer name / id.
+	 * Set the Peer name as a client-side only identifier of this Peer object.
 	 * @param {string} name
 	 */
 	setName(name) {
 		this._name = name;
 	}
 
-    /**
-	 * Set the Peer’s enrollment certificate.
-	 * @param {Object} enrollment Certificate in PEM format signed by the trusted CA
-	 */
-	setEnrollmentCertificate(enrollment) {
-		if (typeof enrollment.privateKey === 'undefined' || enrollment.privateKey === null || enrollment.privateKey === '') {
-			throw new Error('Invalid enrollment object. Must have a valid private key.');
-		}
-
-		if (typeof enrollment.certificate === 'undefined' || enrollment.certificate === null || enrollment.certificate === '') {
-			throw new Error('Invalid enrollment object. Must have a valid certificate.');
-		}
-
-		this._enrollment = enrollment;
-	}
-
 	/**
-	 * Send an endorsement proposal to an endorser.
+	 * Send an endorsement proposal to an endorser. This is used to call an
+	 * endorsing peer to execute a chaincode to process a transaction proposal,
+	 * or runs queries.
 	 *
-	 * @param {Proposal} proposal A proposal of type Proposal
-	 * @see /protos/peer/fabric_proposal.proto
-	 * @returns Promise for a ProposalResponse
+	 * @param {Proposal} proposal - A protobuf encoded byte array of type
+	 *                              [Proposal]{@link https://github.com/hyperledger/fabric/blob/v1.0.0-beta/protos/peer/proposal.proto#L134}
+	 * @returns {Promise} A Promise for a {@link ProposalResponse}
 	 */
 	sendProposal(proposal) {
 		logger.debug('Peer.sendProposal - Start');
@@ -145,8 +124,8 @@ var Peer = class extends Remote {
 	}
 
 	/**
-	* return a printable representation of this object
-	*/
+	 * return a printable representation of this object
+	 */
 	toString() {
 		return ' Peer : {' +
 			'url:' + this._url +

diff --git a/fabric-client/lib/hash.js b/fabric-client/lib/hash.js
@@ -16,9 +16,6 @@
 
 /**
  * Implement hash primitives.
- * Currently SHA3 is implemented, but needs to also add SHA2.
- *
- * NOTE: This is in pure java script to be compatible with the sjcl.hmac function.
  */
 var sjcl = require('sjcl');
 var sjcl_codec = require('sjcl-codec');
@@ -142,7 +139,7 @@ hash_sha3_384.prototype = {
 	}
 };
 
-/**
+/*
  * Convert from a bitArray to bytes (using SJCL's codec)
  * @param {bits} a bitArray to convert from
  * @return {bytes} the bytes converted from the bitArray
@@ -151,7 +148,7 @@ bitsToBytes = function (bits) {
 	return sjcl_codec.bytes.fromBits(bits);
 };
 
-/**
+/*
  * Convert from bytes to a bitArray (using SJCL's codec)
  * @param {bytes} a bytes to convert from
  * @return {bitArray} the bitArray converted from bytes

diff --git a/test/unit/peer.js b/test/unit/peer.js
@@ -37,27 +37,7 @@ test('Peer test', function(t) {
 		'checking the peer setName()'
 	);
 	t.equals('name', peer.getName(), 'checking getName on Peer');
-	t.throws(
-		function () {
-			peer.setEnrollmentCertificate({});
-		},
-		/^Error: Invalid enrollment object. Must have a valid private key./,
-		'Peer checking 	setEnrollmentCertificate(enrollment)'
-	);
-	t.throws(
-		function () {
-			peer.setEnrollmentCertificate({privateKey :'some key'});
-		},
-		/^Error: Invalid enrollment object. Must have a valid certificate./,
-		'Peer checking 	setEnrollmentCertificate(enrollment)'
-	);
-	t.doesNotThrow(
-		function () {
-			peer.setEnrollmentCertificate({privateKey :'some key', certificate : 'some cert'});
-		},
-		null,
-		'checking the peer setEnrollmentCertificate()'
-	);
+
 	t.end();
 });