Merge pull request #287 from lutovich/1.5-result-docs

Improve JSDoc around Result and ResultSummary

Author: lutovich

src/v1/result-summary.js

@@ -17,7 +17,7 @@
  * limitations under the License.
  */
 
-import {int, isInt} from './integer';
+import {isInt} from './integer';
 
 /**
   * A ResultSummary instance contains structured metadata for a {Result}.
@@ -31,19 +31,79 @@ class ResultSummary {
    * @param {Object} metadata - Statement metadata
    */
   constructor(statement, parameters, metadata) {
+    /**
+     * The statement and parameters this summary is for.
+     * @type {{text: string, parameters: Object}}
+     * @public
+     */
     this.statement = {text: statement, parameters};
+
+    /**
+     * The type of statement executed. Can be "r" for read-only statement, "rw" for read-write statement,
+     * "w" for write-only statement and "s" for schema-write statement.
+     * String constants are available in {@link statementType} object.
+     * @type {string}
+     * @public
+     */
     this.statementType = metadata.type;
-    let counters = new StatementStatistics(metadata.stats || {});
-    this.counters = counters;
+
+    /**
+     * Counters for operations the statement triggered.
+     * @type {StatementStatistics}
+     * @public
+     */
+    this.counters = new StatementStatistics(metadata.stats || {});
     //for backwards compatibility, remove in future version
-    this.updateStatistics = counters;
+    this.updateStatistics = this.counters;
+
+    /**
+     * This describes how the database will execute the statement.
+     * Statement plan for the executed statement if available, otherwise undefined.
+     * Will only be populated for queries that start with "EXPLAIN".
+     * @type {Plan}
+     */
     this.plan = metadata.plan || metadata.profile ? new Plan(metadata.plan || metadata.profile) : false;
+
+    /**
+     * This describes how the database did execute your statement. This will contain detailed information about what
+     * each step of the plan did. Profiled statement plan for the executed statement if available, otherwise undefined.
+     * Will only be populated for queries that start with "PROFILE".
+     * @type {ProfiledPlan}
+     * @public
+     */
     this.profile = metadata.profile ? new ProfiledPlan(metadata.profile) : false;
+
+    /**
+     * An array of notifications that might arise when executing the statement. Notifications can be warnings about
+     * problematic statements or other valuable information that can be presented in a client. Unlike failures
+     * or errors, notifications do not affect the execution of a statement.
+     * @type {Array<Notification>}
+     * @public
+     */
     this.notifications = this._buildNotifications(metadata.notifications);
+
+    /**
+     * The basic information of the server where the result is obtained from.
+     * @type {ServerInfo}
+     * @public
+     */
     this.server = new ServerInfo(metadata.server);
+
+    /**
+     * The time it took the server to consume the result.
+     * @type {number}
+     * @public
+     */
     this.resultConsumedAfter = metadata.result_consumed_after;
+
+    /**
+     * The time it took the server to make the result available for consumption in milliseconds.
+     * @type {number}
+     * @public
+     */
     this.resultAvailableAfter = metadata.result_available_after;
   }
+
   _buildNotifications(notifications) {
     if(!notifications) {
       return [];

src/v1/result.js

@@ -27,9 +27,12 @@ const DEFAULT_ON_COMPLETED = summary => {
 };
 
 /**
-  * A stream of {@link Record} representing the result of a statement.
-  * @access public
-  */
+ * A stream of {@link Record} representing the result of a statement.
+ * Can be consumed eagerly as {@link Promise} resolved with {@link Array<Record>} records and {@link ResultSummary}
+ * summary, or rejected with error that contains {@link string} code and {@link string} message.
+ * Alternatively can be consumed lazily using {@link Result.subscribe()}.
+ * @access public
+ */
 class Result {
   /**
    * Inject the observer to be used.
@@ -77,8 +80,9 @@ class Result {
    * Waits for all results and calls the passed in function with the results.
    * Cannot be combined with the {@link #subscribe} function.
    *
-   * @param {function(result: {records:Array<Record>})} onFulfilled - Function to be called when finished.
-   * @param {function(error: {message:string, code:string})} onRejected - Function to be called upon errors.
+   * @param {function(result: {records:Array<Record>, summary: ResultSummary})} onFulfilled - function to be called
+   * when finished.
+   * @param {function(error: {message:string, code:string})} onRejected - function to be called upon errors.
    * @return {Promise} promise.
    */
   then(onFulfilled, onRejected) {
@@ -102,9 +106,9 @@ class Result {
    * of handling the results, and allows you to handle arbitrarily large results.
    *
    * @param {Object} observer - Observer object
-   * @param {function(record: Record)} observer.onNext - Handle records, one by one.
-   * @param {function(metadata: Object)} observer.onCompleted - Handle stream tail, the metadata.
-   * @param {function(error: {message:string, code:string})} observer.onError - Handle errors.
+   * @param {function(record: Record)} observer.onNext - handle records, one by one.
+   * @param {function(summary: ResultSummary)} observer.onCompleted - handle stream tail, the result summary.
+   * @param {function(error: {message:string, code:string})} observer.onError - handle errors.
    * @return
    */
   subscribe(observer) {