Merge pull request #523 from zhenlineo/4.0-api-doc

Improving js driver API doc

Author: zhenlineo

esdoc.json

@@ -36,7 +36,7 @@
           "enable": true
         },
         "brand": {
-          "title": "Neo4j Bolt Driver 2.0 for JavaScript",
+          "title": "Neo4j Bolt Driver 4.0 for JavaScript",
           "repository": "https://github.com/neo4j/neo4j-javascript-driver"
         }
       }

src/driver.js

@@ -102,7 +102,7 @@ class Driver {
    * @public
    * @param {Object} param - The object parameter
    * @param {string} param.database - The target database to verify connectivity for.
-   * @returns {Promise} promise resolved with server info or rejected with error.
+   * @returns {Promise<void>} promise resolved with server info or rejected with error.
    */
   verifyConnectivity ({ database = '' } = {}) {
     const connectionProvider = this._getOrCreateConnectionProvider()
@@ -200,6 +200,7 @@ class Driver {
    * Close all open sessions and other associated resources. You should
    * make sure to use this when you are done with this driver instance.
    * @public
+   * @return {Promise<void>} promise resolved when the driver is closed.
    */
   close () {
     this._log.info(`Driver ${this._id} closing`)

src/error.js

@@ -38,6 +38,13 @@ const SESSION_EXPIRED = 'SessionExpired'
  */
 const PROTOCOL_ERROR = 'ProtocolError'
 
+/**
+ * Create a new error from a message and error code
+ * @param message the error message
+ * @param code the error code
+ * @return {Neo4jError} an {@link Neo4jError}
+ * @private
+ */
 function newError (message, code = 'N/A') {
   // TODO: Idea is that we can check the code here and throw sub-classes
   // of Neo4jError as appropriate
@@ -55,8 +62,20 @@ class Neo4jError extends Error {
    */
   constructor (message, code = 'N/A') {
     super(message)
+    /**
+     * The error message
+     * @type {string}
+     */
     this.message = message
+    /**
+     * Optional error code. Will be populated when error originates in the database.
+     * @type {string}
+     */
     this.code = code
+    /**
+     * The name of the error.
+     * @type {string}
+     */
     this.name = 'Neo4jError'
   }
 }

src/index.js

@@ -56,70 +56,6 @@ import {
 } from './temporal-types'
 import ServerAddress from './internal/server-address'
 
-/**
- * @property {function(username: string, password: string, realm: ?string)} basic the function to create a
- * basic authentication token.
- * @property {function(base64EncodedTicket: string)} kerberos the function to create a Kerberos authentication token.
- * Accepts a single string argument - base64 encoded Kerberos ticket.
- * @property {function(principal: string, credentials: string, realm: string, scheme: string, parameters: ?object)} custom
- * the function to create a custom authentication token.
- */
-const auth = {
-  basic: (username, password, realm = undefined) => {
-    if (realm) {
-      return {
-        scheme: 'basic',
-        principal: username,
-        credentials: password,
-        realm: realm
-      }
-    } else {
-      return { scheme: 'basic', principal: username, credentials: password }
-    }
-  },
-  kerberos: base64EncodedTicket => {
-    return {
-      scheme: 'kerberos',
-      principal: '', // This empty string is required for backwards compatibility.
-      credentials: base64EncodedTicket
-    }
-  },
-  custom: (principal, credentials, realm, scheme, parameters = undefined) => {
-    if (parameters) {
-      return {
-        scheme: scheme,
-        principal: principal,
-        credentials: credentials,
-        realm: realm,
-        parameters: parameters
-      }
-    } else {
-      return {
-        scheme: scheme,
-        principal: principal,
-        credentials: credentials,
-        realm: realm
-      }
-    }
-  }
-}
-const USER_AGENT = 'neo4j-javascript/' + VERSION
-
-/**
- * Object containing predefined logging configurations. These are expected to be used as values of the driver config's `logging` property.
- * @property {function(level: ?string): object} console the function to create a logging config that prints all messages to `console.log` with
- * timestamp, level and message. It takes an optional `level` parameter which represents the maximum log level to be logged. Default value is 'info'.
- */
-const logging = {
-  console: level => {
-    return {
-      level: level,
-      logger: (level, message) =>
-        console.log(`${global.Date.now()} ${level.toUpperCase()} ${message}`)
-    }
-  }
-}
-
 /**
  * Construct a new Neo4j Driver. This is your main entry point for this
  * library.
@@ -234,7 +170,7 @@ const logging = {
  *       },
  *     }
  *
- * @param {string} url The URL for the Neo4j database, for instance "bolt://localhost"
+ * @param {string} url The URL for the Neo4j database, for instance "neo4j://localhost" and/or "bolt://localhost"
  * @param {Map<string,string>} authToken Authentication credentials. See {@link auth} for helpers.
  * @param {Object} config Configuration object. See the configuration section above for details.
  * @returns {Driver}
@@ -267,6 +203,70 @@ function driver (url, authToken, config = {}) {
   }
 }
 
+/**
+ * @property {function(username: string, password: string, realm: ?string)} basic the function to create a
+ * basic authentication token.
+ * @property {function(base64EncodedTicket: string)} kerberos the function to create a Kerberos authentication token.
+ * Accepts a single string argument - base64 encoded Kerberos ticket.
+ * @property {function(principal: string, credentials: string, realm: string, scheme: string, parameters: ?object)} custom
+ * the function to create a custom authentication token.
+ */
+const auth = {
+  basic: (username, password, realm = undefined) => {
+    if (realm) {
+      return {
+        scheme: 'basic',
+        principal: username,
+        credentials: password,
+        realm: realm
+      }
+    } else {
+      return { scheme: 'basic', principal: username, credentials: password }
+    }
+  },
+  kerberos: base64EncodedTicket => {
+    return {
+      scheme: 'kerberos',
+      principal: '', // This empty string is required for backwards compatibility.
+      credentials: base64EncodedTicket
+    }
+  },
+  custom: (principal, credentials, realm, scheme, parameters = undefined) => {
+    if (parameters) {
+      return {
+        scheme: scheme,
+        principal: principal,
+        credentials: credentials,
+        realm: realm,
+        parameters: parameters
+      }
+    } else {
+      return {
+        scheme: scheme,
+        principal: principal,
+        credentials: credentials,
+        realm: realm
+      }
+    }
+  }
+}
+const USER_AGENT = 'neo4j-javascript/' + VERSION
+
+/**
+ * Object containing predefined logging configurations. These are expected to be used as values of the driver config's `logging` property.
+ * @property {function(level: ?string): object} console the function to create a logging config that prints all messages to `console.log` with
+ * timestamp, level and message. It takes an optional `level` parameter which represents the maximum log level to be logged. Default value is 'info'.
+ */
+const logging = {
+  console: level => {
+    return {
+      level: level,
+      logger: (level, message) =>
+        console.log(`${global.Date.now()} ${level.toUpperCase()} ${message}`)
+    }
+  }
+}
+
 /**
  * Object containing constructors for all neo4j types.
  */

src/result-summary.js

@@ -54,13 +54,19 @@ class ResultSummary {
      */
     this.counters = new QueryStatistics(metadata.stats || {})
     // for backwards compatibility, remove in future version
+    /**
+     * Use {@link ResultSummary.counters} instead.
+     * @type {QueryStatistics}
+     * @deprecated
+     */
     this.updateStatistics = this.counters
 
     /**
      * This describes how the database will execute the query.
      * Query plan for the executed query if available, otherwise undefined.
      * Will only be populated for queries that start with "EXPLAIN".
      * @type {Plan}
+     * @public
      */
     this.plan =
       metadata.plan || metadata.profile
@@ -329,6 +335,10 @@ function valueOrDefault (key, values, defaultValue = 0) {
   }
 }
 
+/**
+ * The constants for query types
+ * @type {{SCHEMA_WRITE: string, WRITE_ONLY: string, READ_ONLY: string, READ_WRITE: string}}
+ */
 const queryType = {
   READ_ONLY: 'r',
   READ_WRITE: 'rw',

test/rx/nested-statements.test.js

@@ -31,7 +31,6 @@ import neo4j from '../../src'
 import { ServerVersion, VERSION_4_0_0 } from '../../src/internal/server-version'
 import RxSession from '../../src/session-rx'
 import sharedNeo4j from '../internal/shared-neo4j'
-import { newError } from '../../src/error'
 
 describe('#integration-rx transaction', () => {
   let driver