Address review comments

Author: ali-ince

src/internal/connection-provider-direct.js

@@ -27,6 +27,10 @@ export default class DirectConnectionProvider extends PooledConnectionProvider {
     this._address = address
   }
 
+  /**
+   * See {@link ConnectionProvider} for more information about this method and
+   * its arguments.
+   */
   acquireConnection ({ accessMode, database, bookmarks } = {}) {
     return this._connectionPool
       .acquire(this._address)

src/internal/connection-provider-routing.js

@@ -96,6 +96,10 @@ export default class RoutingConnectionProvider extends PooledConnectionProvider
     )
   }
 
+  /**
+   * See {@link ConnectionProvider} for more information about this method and
+   * its arguments.
+   */
   async acquireConnection ({ accessMode, database, bookmark } = {}) {
     let name
     let address

src/internal/connection-provider-single.js

@@ -25,6 +25,10 @@ export default class SingleConnectionProvider extends ConnectionProvider {
     this._connection = connection
   }
 
+  /**
+   * See {@link ConnectionProvider} for more information about this method and
+   * its arguments.
+   */
   acquireConnection ({ accessMode, database, bookmarks } = {}) {
     const connection = this._connection
     this._connection = null

src/internal/connection-provider.js

@@ -1,3 +1,5 @@
+import Bookmark from './bookmark'
+
 /**
  * Copyright (c) 2002-2019 "Neo4j,"
  * Neo4j Sweden AB [http://neo4j.com]
@@ -18,10 +20,29 @@
  */
 
 export default class ConnectionProvider {
+  /**
+   * This method acquires a connection against the specified database.
+   *
+   * Access mode and Bookmarks only applies to routing driver. Access mode only
+   * differentiates the target server for the connection, where WRITE selects a
+   * WRITER server, whereas READ selects a READ server. Bookmarks, when specified,
+   * is only passed to the routing discovery procedure, for the system database to
+   * synchronize on creation of databases and is never used in direct drivers.
+   *
+   * @param {object} param - object parameter
+   * @param {string} param.accessMode - the access mode for the to-be-acquired connection
+   * @param {string} param.database - the target database for the to-be-acquired connection
+   * @param {Bookmark} param.bookmarks - the bookmarks to send to routing discovery
+   */
   acquireConnection ({ accessMode, database, bookmarks } = {}) {
     throw new Error('not implemented')
   }
 
+  /**
+   * Closes this connection provider along with its internals (connections, pools, etc.)
+   *
+   * @returns {Promise<void>}
+   */
   close () {
     throw new Error('not implemented')
   }

test/internal/bookmark.test.js

@@ -90,6 +90,30 @@ describe('#unit Bookmark', () => {
     ])
   })
 
+  it('should be possible to construct bookmark from nested arrays with null and undefined elements', () => {
+    const bookmark = new Bookmark([
+      'neo4j:bookmark:v1:tx1',
+      null,
+      undefined,
+      ['neo4j:bookmark:v1:tx2'],
+      [undefined],
+      [
+        ['neo4j:bookmark:v1:tx3', 'neo4j:bookmark:v1:tx4'],
+        [undefined, 'neo4j:bookmark:v1:tx5', 'neo4j:bookmark:v1:tx6', null]
+      ]
+    ])
+
+    expect(bookmark.isEmpty()).toBeFalsy()
+    expect(bookmark.values()).toEqual([
+      'neo4j:bookmark:v1:tx1',
+      'neo4j:bookmark:v1:tx2',
+      'neo4j:bookmark:v1:tx3',
+      'neo4j:bookmark:v1:tx4',
+      'neo4j:bookmark:v1:tx5',
+      'neo4j:bookmark:v1:tx6'
+    ])
+  })
+
   it('should not be possible to construct bookmark from object', () => {
     expect(() => new Bookmark({})).toThrowError(TypeError)
     expect(