Improve documentation

Author: ali-ince

src/docs.js

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) 2002-2019 "Neo4j,"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Configuration object containing settings for explicit and auto-commit transactions.
+ * <p>
+ * Configuration is supported for:
+ * <ul>
+ *   <li>queries executed in auto-commit transactions using {@link Session#run} and {@link RxSession#run}</li>
+ *   <li>transactions started by transaction functions using {@link Session#readTransaction}, {@link RxSession#readTransaction},
+ * {@link Session#writeTransaction} and {@link RxSession#writeTransaction}</li>
+ *   <li>explicit transactions using {@link Session#beginTransaction} and {@link RxSession#beginTransaction}</li>
+ * </ul>
+ * @typedef {Object} TransactionConfig
+ * @property {number} timeout - the transaction timeout in **milliseconds**. Transactions that execute longer than the configured timeout will
+ * be terminated by the database. This functionality allows to limit query/transaction execution time. Specified timeout overrides the default timeout
+ * configured in the database using `dbms.transaction.timeout` setting. Value should not represent a duration of zero or negative duration.
+ * @property {Object} metadata - the transaction metadata. Specified metadata will be attached to the executing transaction and visible in the output of
+ * `dbms.listQueries` and `dbms.listTransactions` procedures. It will also get logged to the `query.log`. This functionality makes it easier to tag
+ * transactions and is equivalent to `dbms.setTXMetaData` procedure.
+ */

src/driver.js

@@ -63,11 +63,11 @@ class Driver {
   /**
    * You should not be calling this directly, instead use {@link driver}.
    * @constructor
+   * @protected
    * @param {ServerAddress} address
    * @param {string} userAgent
-   * @param {object} authToken
-   * @param {object} config
-   * @protected
+   * @param {Object} authToken
+   * @param {Object} config
    */
   constructor (address, userAgent, authToken = {}, config = {}) {
     sanitizeConfig(config)
@@ -89,19 +89,13 @@ class Driver {
     this._afterConstruction()
   }
 
-  /**
-   * @protected
-   */
-  _afterConstruction () {
-    this._log.info(
-      `Direct driver ${this._id} created for server address ${this._address}`
-    )
-  }
-
   /**
    * Verifies connectivity of this driver by trying to open a connection with the provided driver options.
-   * @param {string} [database=''] the target database to verify connectivity for.
-   * @returns {Promise<object>} promise resolved with server info or rejected with error.
+   *
+   * @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.
    */
   verifyConnectivity ({ database = '' } = {}) {
     const connectionProvider = this._getOrCreateConnectionProvider()
@@ -120,11 +114,12 @@ class Driver {
    * it is closed, the underlying connection will be released to the connection
    * pool and made available for others to use.
    *
-   * @param {Object} args -
-   * @param {string} args.defaultAccessMode='WRITE' - the access mode of this session, allowed values are {@link READ} and {@link WRITE}.
-   * @param {string|string[]} args.bookmarks - the initial reference or references to some previous
+   * @public
+   * @param {Object} param - The object parameter
+   * @param {string} param.defaultAccessMode=WRITE - the access mode of this session, allowed values are {@link READ} and {@link WRITE}.
+   * @param {string|string[]} param.bookmarks - the initial reference or references to some previous
    * transactions. Value is optional and absence indicates that that the bookmarks do not exist or are unknown.
-   * @param {string} args.database='' - the database this session will connect to.
+   * @param {string} param.database - the database this session will operate on.
    * @return {Session} new session.
    */
   session ({
@@ -140,6 +135,25 @@ class Driver {
     })
   }
 
+  /**
+   * Acquire a reactive session to communicate with the database. The session will
+   * borrow connections from the underlying connection pool as required and
+   * should be considered lightweight and disposable.
+   *
+   * This comes with some responsibility - make sure you always call
+   * {@link close} when you are done using a session, and likewise,
+   * make sure you don't close your session before you are done using it. Once
+   * it is closed, the underlying connection will be released to the connection
+   * pool and made available for others to use.
+   *
+   * @public
+   * @param {Object} param
+   * @param {string} param.defaultAccessMode=WRITE - the access mode of this session, allowed values are {@link READ} and {@link WRITE}
+   * @param {string|string[]} param.bookmarks - the initial reference or references to some previous transactions. Value is optional and
+   * absence indicates that the bookmarks do not exist or are unknown.
+   * @param {string} param.database - the database this session will operate on.
+   * @returns {RxSession} new reactive session.
+   */
   rxSession ({ defaultAccessMode = WRITE, bookmarks, database = '' } = {}) {
     return new RxSession({
       session: this._newSession({
@@ -152,22 +166,44 @@ class Driver {
     })
   }
 
-  _newSession ({ defaultAccessMode, bookmarkOrBookmarks, database, reactive }) {
-    const sessionMode = Driver._validateSessionMode(defaultAccessMode)
-    const connectionProvider = this._getOrCreateConnectionProvider()
-    const bookmark = bookmarkOrBookmarks
-      ? new Bookmark(bookmarkOrBookmarks)
-      : Bookmark.empty()
-    return new Session({
-      mode: sessionMode,
-      database,
-      connectionProvider,
-      bookmark,
+  /**
+   * Close all open sessions and other associated resources. You should
+   * make sure to use this when you are done with this driver instance.
+   * @public
+   */
+  close () {
+    this._log.info(`Driver ${this._id} closing`)
+    if (this._connectionProvider) {
+      this._connectionProvider.close()
+    }
+  }
+
+  /**
+   * @protected
+   */
+  _afterConstruction () {
+    this._log.info(
+      `Direct driver ${this._id} created for server address ${this._address}`
+    )
+  }
+
+  /**
+   * @protected
+   */
+  _createConnectionProvider (address, userAgent, authToken) {
+    return new DirectConnectionProvider({
+      id: this._id,
       config: this._config,
-      reactive
+      log: this._log,
+      address: address,
+      userAgent: userAgent,
+      authToken: authToken
     })
   }
 
+  /**
+   * @protected
+   */
   static _validateSessionMode (rawMode) {
     const mode = rawMode || WRITE
     if (mode !== ACCESS_MODE_READ && mode !== ACCESS_MODE_WRITE) {
@@ -176,18 +212,28 @@ class Driver {
     return mode
   }
 
-  // Extension point
-  _createConnectionProvider (address, userAgent, authToken) {
-    return new DirectConnectionProvider({
-      id: this._id,
+  /**
+   * @private
+   */
+  _newSession ({ defaultAccessMode, bookmarkOrBookmarks, database, reactive }) {
+    const sessionMode = Driver._validateSessionMode(defaultAccessMode)
+    const connectionProvider = this._getOrCreateConnectionProvider()
+    const bookmark = bookmarkOrBookmarks
+      ? new Bookmark(bookmarkOrBookmarks)
+      : Bookmark.empty()
+    return new Session({
+      mode: sessionMode,
+      database,
+      connectionProvider,
+      bookmark,
       config: this._config,
-      log: this._log,
-      address: address,
-      userAgent: userAgent,
-      authToken: authToken
+      reactive
     })
   }
 
+  /**
+   * @private
+   */
   _getOrCreateConnectionProvider () {
     if (!this._connectionProvider) {
       this._connectionProvider = this._createConnectionProvider(
@@ -199,18 +245,6 @@ class Driver {
 
     return this._connectionProvider
   }
-
-  /**
-   * Close all open sessions and other associated resources. You should
-   * make sure to use this when you are done with this driver instance.
-   * @return undefined
-   */
-  close () {
-    this._log.info(`Driver ${this._id} closing`)
-    if (this._connectionProvider) {
-      this._connectionProvider.close()
-    }
-  }
 }
 
 /**
@@ -231,6 +265,9 @@ function sanitizeConfig (config) {
   )
 }
 
+/**
+ * @private
+ */
 function sanitizeIntValue (rawValue, defaultWhenAbsent) {
   const sanitizedValue = parseInt(rawValue, 10)
   if (sanitizedValue > 0 || sanitizedValue === 0) {