Working on documentation (wip)

.gitignore

@@ -39,4 +39,4 @@ node_modules
 lib/
 .eslintrc.json
 jsconfig.json
-
+docs/

.idea/eventstore-node.iml

@@ -3,6 +3,7 @@
   <component name="NewModuleRootManager">
     <content url="file://$MODULE_DIR$">
       <sourceFolder url="file://$MODULE_DIR$/test" isTestSource="true" />
+      <excludeFolder url="file://$MODULE_DIR$/docs" />
       <excludeFolder url="file://$MODULE_DIR$/lib" />
     </content>
     <orderEntry type="inheritedJdk" />

package.json

@@ -8,7 +8,8 @@
     "build": "webpack",
     "pretest": "npm run build",
     "test": "nodeunit",
-    "prepublish": "npm run build"
+    "prepublish": "npm run build",
+    "gendocs": "rm -rf docs && jsdoc src -r -R README.md -P package.json -d docs"
   },
   "files": [
     "lib",

src/client.js

@@ -12,31 +12,35 @@ const positions = {
 };
 
 /**
- * @param {string} eventId
- * @param {object} event
- * @param {object} [metadata]
- * @param {string} [type]
+ * Create an EventData object from JavaScript event/metadata that will be serialized as json
+ * @public
+ * @param {string} eventId    Event UUID
+ * @param {object} event      Event object
+ * @param {object} [metadata] Event metadata
+ * @param {string} [type]     Event type
  * @returns {EventData}
  */
-function jsonEventDataFactory(eventId, event, metadata, type) {
+module.exports.createJsonEventData = function (eventId, event, metadata, type) {
   if (!event || typeof event !== 'object') throw new TypeError("data must be an object.");
 
   var eventBuf = new Buffer(JSON.stringify(event));
   var metaBuf = metadata ? new Buffer(JSON.stringify(metadata)) : null;
   return new EventData(eventId, type || event.constructor.name, true, eventBuf, metaBuf);
-}
+};
 
 /**
- * @param {string} eventId
- * @param {string} type
- * @param {boolean} isJson
- * @param {Buffer} data
- * @param {Buffer} [metadata]
+ * Create an EventData object from event/metadata buffer(s)
+ * @public
+ * @param {string} eventId    Event UUID
+ * @param {string} type       Event type
+ * @param {boolean} isJson    is buffer(s) content json
+ * @param {Buffer} data       Data buffer
+ * @param {Buffer} [metadata] Metadata buffer
  * @returns {EventData}
  */
-function eventDataFactory(eventId, type, isJson, data, metadata) {
+module.exports.createEventData = function (eventId, type, isJson, data, metadata) {
   return new EventData(eventId, type, isJson, data, metadata);
-}
+};
 
 // Expose classes
 module.exports.EventStoreConnection = require('./eventStoreConnection');
@@ -60,5 +64,3 @@ module.exports.NoopLogger = require('./common/log/noopLogger');
 module.exports.FileLogger = require('./common/log/fileLogger');
 // Expose Helper functions
 module.exports.createConnection = module.exports.EventStoreConnection.create;
-module.exports.createEventData = eventDataFactory;
-module.exports.createJsonEventData = jsonEventDataFactory;

src/clientOperations/operationBase.js

@@ -75,7 +75,7 @@ OperationBase.prototype.inspectPackage = function(pkg) {
       case TcpCommand.NotHandled:
         return this._inspectNotHandled(pkg);
       default:
-        return this._inspectUnexpectedCommand(package, this._responseCommand);
+        return this._inspectUnexpectedCommand(pkg, this._responseCommand);
     }
   } catch(e) {
     this.fail(e);
@@ -136,7 +136,7 @@ OperationBase.prototype._inspectUnexpectedCommand = function(pkg, expectedComman
   this.log.error("Unexpected TcpCommand received.\n"
       + "Expected: %s, Actual: %s, Flags: %s, CorrelationId: %s\n"
       + "Operation (%s): %s\n"
-      +"TcpPackage Data Dump:\n%j",
+      + "TcpPackage Data Dump:\n%j",
       expectedCommand, TcpCommand.getName(pkg.command), pkg.flags, pkg.correlationId,
       this.constructor.name, this, pkg.data);
 

src/common/bufferSegment.js

@@ -1,5 +1,6 @@
 /**
  * Create a buffer segment
+ * @private
  * @param {Buffer} buf
  * @param {number} [offset]
  * @param {number} [count]

src/common/hash.js

@@ -1,4 +1,5 @@
 /**
+ * @private
  * @constructor
  * @property {number} length
  */

src/core/eventStoreConnectionLogicHandler.js

@@ -36,6 +36,7 @@ const TimerTickMessage = new messages.TimerTickMessage();
 const EmptyGuid = '00000000-0000-0000-0000-000000000000';
 
 /**
+ * @private
  * @param {EventStoreNodeConnection} esConnection
  * @param {Object} settings
  * @constructor

src/core/messages.js

@@ -41,6 +41,7 @@ function StartSubscriptionMessage(
 util.inherits(StartSubscriptionMessage, Message);
 
 /**
+ * @private
  * @constructor
  * @property {object} endPoints
  * @property {object} endPoints.secureTcpEndPoint

src/core/operationsManager.js

@@ -5,6 +5,7 @@ var Hash = require('../common/hash');
 var TcpCommand = require('../systemData/tcpCommand');
 
 /**
+ * @private
  * @param {string} connectionName
  * @param {object} settings
  * @constructor

src/eventData.js

@@ -12,6 +12,7 @@ function isValidId(id) {
 
 /**
  * Create an EventData
+ * @private
  * @param {string} eventId
  * @param {string} type
  * @param {boolean} [isJson]

src/eventStoreConnection.js

@@ -97,6 +97,8 @@ function createFromGossipSeeds(connectionSettings, gossipSeeds, connectionName)
 
 /**
  * Create an EventStore connection
+ * @public
+ * @alias createConnection
  * @param {object} settings
  * @param {string|object|array} endPointOrGossipSeeds
  * @param {string} [connectionName]

src/eventStoreNodeConnection.js

@@ -33,12 +33,8 @@ var EventData = require('./eventData');
 const MaxReadSize = 4096;
 
 /**
- * @param settings
- * @param clusterSettings
- * @param endpointDiscoverer
- * @param connectionName
+ * @protected
  * @constructor
- * @property {string} connectionName
  */
 function EventStoreNodeConnection(settings, clusterSettings, endpointDiscoverer, connectionName) {
   this._connectionName = connectionName || ['ES-', uuid.v4()].join('');
@@ -73,6 +69,8 @@ Object.defineProperty(EventStoreNodeConnection.prototype, 'connectionName', {
 });
 
 /**
+ * Start connection task
+ * @public
  * @returns {Promise}
  */
 EventStoreNodeConnection.prototype.connect = function() {
@@ -87,12 +85,17 @@ EventStoreNodeConnection.prototype.connect = function() {
   });
 };
 
+/**
+ * Close connection
+ * @public
+ */
 EventStoreNodeConnection.prototype.close = function() {
   this._handler.enqueueMessage(new messages.CloseConnectionMessage("Connection close requested by client.", null));
 };
 
 /**
  * Delete a stream (async)
+ * @public
  * @param {string} stream
  * @param {number} expectedVersion
  * @param {boolean} [hardDelete]
@@ -120,6 +123,7 @@ EventStoreNodeConnection.prototype.deleteStream = function(stream, expectedVersi
 
 /**
  * Append events to a stream (async)
+ * @public
  * @param {string} stream The name of the stream to which to append.
  * @param {number} expectedVersion The version at which we currently expect the stream to be in order that an optimistic concurrency check can be performed.
  * @param {EventData[]|EventData} events The event(s) to append.
@@ -148,6 +152,7 @@ EventStoreNodeConnection.prototype.appendToStream = function(stream, expectedVer
 
 /**
  * Start a transaction (async)
+ * @public
  * @param {string} stream
  * @param {number} expectedVersion
  * @param {UserCredentials} [userCredentials]
@@ -172,6 +177,7 @@ EventStoreNodeConnection.prototype.startTransaction = function(stream, expectedV
 
 /**
  * Continue a transaction
+ * @public
  * @param {number} transactionId
  * @param {UserCredentials} userCredentials
  * @returns {EventStoreTransaction}
@@ -199,6 +205,13 @@ EventStoreNodeConnection.prototype.transactionalWrite = function(transaction, ev
   });
 };
 
+/**
+ * Commit a transaction
+ * @public
+ * @param transaction
+ * @param userCredentials
+ * @returns {Promise.<WriteResult>}
+ */
 EventStoreNodeConnection.prototype.commitTransaction = function(transaction, userCredentials) {
   ensure.isTypeOf(EventStoreTransaction, transaction, "transaction");
 
@@ -216,6 +229,7 @@ EventStoreNodeConnection.prototype.commitTransaction = function(transaction, use
 
 /**
  * Read a single event (async)
+ * @public
  * @param {string} stream
  * @param {number} eventNumber
  * @param {boolean} [resolveLinkTos]
@@ -248,6 +262,7 @@ EventStoreNodeConnection.prototype.readEvent = function(stream, eventNumber, res
 
 /**
  * Reading a specific stream forwards (async)
+ * @public
  * @param {string} stream
  * @param {number} start
  * @param {number} count
@@ -281,6 +296,7 @@ EventStoreNodeConnection.prototype.readStreamEventsForward = function(
 
 /**
  * Reading a specific stream backwards (async)
+ * @public
  * @param {string} stream
  * @param {number} start
  * @param {number} count
@@ -313,6 +329,7 @@ EventStoreNodeConnection.prototype.readStreamEventsBackward = function(
 
 /**
  * Reading all events forwards (async)
+ * @public
  * @param {Position} position
  * @param {number} maxCount
  * @param {boolean} [resolveLinkTos]
@@ -343,6 +360,7 @@ EventStoreNodeConnection.prototype.readAllEventsForward = function(
 
 /**
  * Reading all events backwards (async)
+ * @public
  * @param {Position} position
  * @param {number} maxCount
  * @param {boolean} [resolveLinkTos]
@@ -373,6 +391,7 @@ EventStoreNodeConnection.prototype.readAllEventsBackward = function(
 
 /**
  * Subscribe to a stream (async)
+ * @public
  * @param {!string} stream
  * @param {!boolean} resolveLinkTos
  * @param {function} eventAppeared
@@ -402,6 +421,8 @@ EventStoreNodeConnection.prototype.subscribeToStream = function(
 };
 
 /**
+ * Subscribe to a stream from position
+ * @public
  * @param {!string} stream
  * @param {?number} lastCheckpoint
  * @param {!boolean} resolveLinkTos
@@ -430,6 +451,7 @@ EventStoreNodeConnection.prototype.subscribeToStreamFrom = function(
 
 /**
  * Subscribe to all (async)
+ * @public
  * @param {!boolean} resolveLinkTos
  * @param {!function} eventAppeared
  * @param {function} [subscriptionDropped]
@@ -456,6 +478,7 @@ EventStoreNodeConnection.prototype.subscribeToAll = function(
 
 /**
  * Subscribe to all from
+ * @public
  * @param {?Position} lastCheckpoint
  * @param {!boolean} resolveLinkTos
  * @param {!function} eventAppeared
@@ -481,6 +504,7 @@ EventStoreNodeConnection.prototype.subscribeToAllFrom = function(
 
 /**
  * Subscribe to a persistent subscription
+ * @public
  * @param {string} stream
  * @param {string} groupName
  * @param {function} eventAppeared
@@ -488,6 +512,7 @@ EventStoreNodeConnection.prototype.subscribeToAllFrom = function(
  * @param {UserCredentials} [userCredentials]
  * @param {number} [bufferSize]
  * @param {boolean} [autoAck]
+ * @return {EventStorePersistentSubscription}
  */
 EventStoreNodeConnection.prototype.connectToPersistentSubscription = function(
     stream, groupName, eventAppeared, subscriptionDropped, userCredentials, bufferSize, autoAck
@@ -510,6 +535,8 @@ EventStoreNodeConnection.prototype.connectToPersistentSubscription = function(
 };
 
 /**
+ * Create a persistent subscription
+ * @public
  * @param {string} stream
  * @param {string} groupName
  * @param {PersistentSubscriptionSettings} settings
@@ -533,6 +560,8 @@ EventStoreNodeConnection.prototype.createPersistentSubscription = function(strea
 };
 
 /**
+ * Update a persistent subscription
+ * @public
  * @param {string} stream
  * @param {string} groupName
  * @param {string} settings
@@ -555,6 +584,8 @@ EventStoreNodeConnection.prototype.updatePersistentSubscription = function(strea
 };
 
 /**
+ * Delete a persistent subscription
+ * @public
  * @param {string} stream
  * @param {string} groupName
  * @param {UserCredentials} [userCredentials]
@@ -574,6 +605,10 @@ EventStoreNodeConnection.prototype.deletePersistentSubscription = function(strea
   });
 };
 
+/**
+ * Set stream metadata
+ * @private
+ */
 EventStoreNodeConnection.prototype.setStreamMetadata = function() {
   //TODO: set stream metadata (non-raw)
   throw new Error("Not implemented.");
@@ -581,6 +616,7 @@ EventStoreNodeConnection.prototype.setStreamMetadata = function() {
 
 /**
  * Set stream metadata with raw object (async)
+ * @public
  * @param {string} stream
  * @param {number} expectedMetastreamVersion
  * @param {object} metadata
@@ -608,6 +644,12 @@ EventStoreNodeConnection.prototype.setStreamMetadataRaw = function(
   });
 };
 
+/**
+ * Get stream metadata
+ * @private
+ * @param stream
+ * @param userCredentials
+ */
 EventStoreNodeConnection.prototype.getStreamMetadata = function(stream, userCredentials) {
   //TODO: get stream metadata (non-raw)
   throw new Error("Not implemented.");
@@ -615,6 +657,7 @@ EventStoreNodeConnection.prototype.getStreamMetadata = function(stream, userCred
 
 /**
  * Get stream metadata as raw object (async)
+ * @public
  * @param {string} stream
  * @param {UserCredentials} [userCredentials]
  * @returns {Promise.<RawStreamMetadataResult>}
@@ -640,6 +683,10 @@ EventStoreNodeConnection.prototype.getStreamMetadataRaw = function(stream, userC
       });
 };
 
+/**
+ * Set system settings
+ * @private
+ */
 EventStoreNodeConnection.prototype.setSystemSettings = function() {
   //TODO: set system settings
   throw new Error("Not implemented.");

src/results.js

@@ -4,6 +4,7 @@ var Long = require('long');
 var ensure = require('./common/utils/ensure');
 
 /**
+ * @public
  * @param {!number|!Long} commitPosition
  * @param {!number|!Long} preparePosition
  * @constructor

src/transport/tcp/tcpPackageConnection.js

@@ -7,6 +7,7 @@ var TcpPackage = require('../../systemData/tcpPackage');
 var TcpCommand = require('../../systemData/tcpCommand');
 
 /**
+ * @private
  * @param log
  * @param remoteEndPoint
  * @param connectionId

src/volatileEventStoreSubscription.js

@@ -3,6 +3,7 @@ var util = require('util');
 var EventStoreSubsription = require('./eventStoreSubscription');
 
 /**
+ * @private
  * @param {SubscriptionOperation} subscriptionOperation
  * @param {string} streamId
  * @param {Position} lastCommitPosition