From d7eb818024d6315586cff96d655a99cfda04db6d Mon Sep 17 00:00:00 2001 From: martin bendsoe Date: Tue, 3 Dec 2019 13:36:47 +0100 Subject: [PATCH] JSDocs updates and fixes. Minor typo fixes in JSDocs. Nothing Major found to be fixed. - Cypher queries examples uses the dollar sign now. --- README.md | 10 ++-- src/driver.js | 20 +++---- src/session.js | 34 ++++++------ src/spatial-types.js | 10 ++-- src/temporal-types.js | 118 +++++++++++++++++++++--------------------- 5 files changed, 96 insertions(+), 96 deletions(-) diff --git a/README.md b/README.md index bbb19ca3c..81b47c582 100644 --- a/README.md +++ b/README.md @@ -307,7 +307,7 @@ var writeTxResultPromise = session.writeTransaction(async txc => { // used transaction will be committed automatically, no need for explicit commit/rollback var result = await txc.run( - "MERGE (alice:Person {name : 'Alice' }) RETURN alice.name AS name" + "MERGE (alice:Person {name : 'Alice'}) RETURN alice.name AS name" ) // at this point it is possible to either return the result or process it and return the // result of processing it is also possible to run more statements in the same transaction @@ -430,19 +430,19 @@ _**Any javascript number value passed as a parameter will be recognized as `Floa #### Writing integers -Numbers written directly e.g. `session.run("CREATE (n:Node {age: {age}})", {age: 22})` will be of type `Float` in Neo4j. +Numbers written directly e.g. `session.run("CREATE (n:Node {age: $age})", {age: 22})` will be of type `Float` in Neo4j. To write the `age` as an integer the `neo4j.int` method should be used: ```javascript var neo4j = require('neo4j-driver') -session.run('CREATE (n {age: {myIntParam}})', { myIntParam: neo4j.int(22) }) +session.run('CREATE (n {age: $myIntParam})', { myIntParam: neo4j.int(22) }) ``` To write integers larger than can be represented as JavaScript numbers, use a string argument to `neo4j.int`: ```javascript -session.run('CREATE (n {age: {myIntParam}})', { +session.run('CREATE (n {age: $myIntParam})', { myIntParam: neo4j.int('9223372036854775807') }) ``` @@ -505,7 +505,7 @@ To run tests against "default" Neo4j version: To run tests against specified Neo4j version: -./runTests.sh '-e 3.1.3' + ./runTests.sh '-e 4.0.0' Simple `npm test` can also be used if you already have a running version of a compatible Neo4j server. diff --git a/src/driver.js b/src/driver.js index d53172506..8feaf8d9f 100644 --- a/src/driver.js +++ b/src/driver.js @@ -101,7 +101,7 @@ class Driver { * * @public * @param {Object} param - The object parameter - * @param {string} param.database - the target database to verify connectivity for. + * @param {string} param.database - The target database to verify connectivity for. * @returns {Promise} promise resolved with server info or rejected with error. */ verifyConnectivity ({ database = '' } = {}) { @@ -111,8 +111,8 @@ class Driver { } /** - * Returns whether the server supports multi database capabilities based on the handshaked protocol - * version. + * Returns whether the server supports multi database capabilities based on the protocol + * version negotiated via handshake. * * Note that this function call _always_ causes a round-trip to the server. * @@ -136,12 +136,12 @@ class Driver { * * @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 + * @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 {number} param.fetchSize - the record fetch size of each batch of this session. + * @param {number} param.fetchSize - The record fetch size of each batch of this session. * Use {@link ALL} to always pull all records in one batch. This will override the config value set on driver config. - * @param {string} param.database - the database this session will operate on. + * @param {string} param.database - The database this session will operate on. * @return {Session} new session. */ session ({ @@ -172,10 +172,10 @@ class Driver { * * @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 + * @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. + * @param {string} param.database - The database this session will operate on. * @returns {RxSession} new reactive session. */ rxSession ({ diff --git a/src/session.js b/src/session.js index e4f0f4043..aa62cd373 100644 --- a/src/session.js +++ b/src/session.js @@ -44,12 +44,12 @@ class Session { * @protected * @param {Object} args * @param {string} args.mode the default access mode for this session. - * @param {ConnectionProvider} args.connectionProvider - the connection provider to acquire connections from. - * @param {Bookmark} args.bookmark - the initial bookmark for this session. + * @param {ConnectionProvider} args.connectionProvider - The connection provider to acquire connections from. + * @param {Bookmark} args.bookmark - The initial bookmark for this session. * @param {string} args.database the database name - * @param {Object} args.config={} - this driver configuration. - * @param {boolean} args.reactive - whether this session should create reactive streams - * @param {number} args.fetchSize - defines how many records is pulled in each pulling batch + * @param {Object} args.config={} - This driver configuration. + * @param {boolean} args.reactive - Whether this session should create reactive streams + * @param {number} args.fetchSize - Defines how many records is pulled in each pulling batch */ constructor ({ mode, @@ -91,8 +91,8 @@ class Session { * @public * @param {mixed} query - Cypher query to execute * @param {Object} parameters - Map with parameters to use in query - * @param {TransactionConfig} [transactionConfig] - configuration for the new auto-commit transaction. - * @return {Result} - New Result + * @param {TransactionConfig} [transactionConfig] - Configuration for the new auto-commit transaction. + * @return {Result} New Result. */ run (query, parameters, transactionConfig) { const { validatedQuery, params } = validateQueryAndParameters( @@ -151,8 +151,8 @@ class Session { * * While a transaction is open the session cannot be used to run queries outside the transaction. * - * @param {TransactionConfig} [transactionConfig] - configuration for the new auto-commit transaction. - * @returns {Transaction} - New Transaction + * @param {TransactionConfig} [transactionConfig] - Configuration for the new auto-commit transaction. + * @returns {Transaction} New Transaction. */ beginTransaction (transactionConfig) { // this function needs to support bookmarks parameter for backwards compatibility @@ -202,7 +202,7 @@ class Session { /** * Return the bookmark received following the last completed {@link Transaction}. * - * @return {string[]} a reference to a previous transaction + * @return {string[]} A reference to a previous transaction. */ lastBookmark () { return this._lastBookmark.values() @@ -216,10 +216,10 @@ class Session { * delay of 1 second and maximum retry time of 30 seconds. Maximum retry time is configurable via driver config's * `maxTransactionRetryTime` property in milliseconds. * - * @param {function(tx: Transaction): Promise} transactionWork - callback that executes operations against + * @param {function(tx: Transaction): Promise} transactionWork - Callback that executes operations against * a given {@link Transaction}. - * @param {TransactionConfig} [transactionConfig] - configuration for all transactions started to execute the unit of work. - * @return {Promise} resolved promise as returned by the given function or rejected promise when given + * @param {TransactionConfig} [transactionConfig] - Configuration for all transactions started to execute the unit of work. + * @return {Promise} Resolved promise as returned by the given function or rejected promise when given * function or commit fails. */ readTransaction (transactionWork, transactionConfig) { @@ -235,10 +235,10 @@ class Session { * delay of 1 second and maximum retry time of 30 seconds. Maximum retry time is configurable via driver config's * `maxTransactionRetryTime` property in milliseconds. * - * @param {function(tx: Transaction): Promise} transactionWork - callback that executes operations against + * @param {function(tx: Transaction): Promise} transactionWork - Callback that executes operations against * a given {@link Transaction}. - * @param {TransactionConfig} [transactionConfig] - configuration for all transactions started to execute the unit of work. - * @return {Promise} resolved promise as returned by the given function or rejected promise when given + * @param {TransactionConfig} [transactionConfig] - Configuration for all transactions started to execute the unit of work. + * @return {Promise} Resolved promise as returned by the given function or rejected promise when given * function or commit fails. */ writeTransaction (transactionWork, transactionConfig) { @@ -255,7 +255,7 @@ class Session { /** * Update value of the last bookmark. - * @param {Bookmark} newBookmark the new bookmark. + * @param {Bookmark} newBookmark - The new bookmark. */ _updateBookmark (newBookmark) { if (newBookmark && !newBookmark.isEmpty()) { diff --git a/src/spatial-types.js b/src/spatial-types.js index fc96ceb7c..b16b001f2 100644 --- a/src/spatial-types.js +++ b/src/spatial-types.js @@ -27,15 +27,15 @@ const POINT_IDENTIFIER_PROPERTY = '__isPoint__' export class Point { /** * @constructor - * @param {Integer|number} srid the coordinate reference system identifier. - * @param {number} x the `x` coordinate of the point. - * @param {number} y the `y` coordinate of the point. - * @param {number} [z=undefined] the `z` coordinate of the point or `undefined` if point has 2 dimensions. + * @param {Integer|number} srid - The coordinate reference system identifier. + * @param {number} x - The `x` coordinate of the point. + * @param {number} y - The `y` coordinate of the point. + * @param {number} [z=undefined] - The `z` coordinate of the point or `undefined` if point has 2 dimensions. */ constructor (srid, x, y, z) { /** * The coordinate reference system identifier. - * @type {Integer|Number} + * @type {Integer|number} */ this.srid = assertNumberOrInteger(srid, 'SRID') /** diff --git a/src/temporal-types.js b/src/temporal-types.js index 7c524244c..bb821000f 100644 --- a/src/temporal-types.js +++ b/src/temporal-types.js @@ -46,10 +46,10 @@ const DATE_TIME_IDENTIFIER_PROPERTY = '__isDateTime__' export class Duration { /** * @constructor - * @param {Integer|number} months the number of months for the new duration. - * @param {Integer|number} days the number of days for the new duration. - * @param {Integer|number} seconds the number of seconds for the new duration. - * @param {Integer|number} nanoseconds the number of nanoseconds for the new duration. + * @param {Integer|number} months - The number of months for the new duration. + * @param {Integer|number} days - The number of days for the new duration. + * @param {Integer|number} seconds - The number of seconds for the new duration. + * @param {Integer|number} nanoseconds - The number of nanoseconds for the new duration. */ constructor (months, days, seconds, nanoseconds) { /** @@ -107,15 +107,15 @@ export function isDuration (obj) { /** * Represents an instant capturing the time of day, but not the date, nor the timezone. - * Created `LocalTime` objects are frozen with `Object.freeze()` in constructor and thus immutable. + * Created {@link LocalTime} objects are frozen with `Object.freeze()` in constructor and thus immutable. */ export class LocalTime { /** * @constructor - * @param {Integer|number} hour the hour for the new local time. - * @param {Integer|number} minute the minute for the new local time. - * @param {Integer|number} second the second for the new local time. - * @param {Integer|number} nanosecond the nanosecond for the new local time. + * @param {Integer|number} hour - The hour for the new local time. + * @param {Integer|number} minute - The minute for the new local time. + * @param {Integer|number} second - The second for the new local time. + * @param {Integer|number} nanosecond - The nanosecond for the new local time. */ constructor (hour, minute, second, nanosecond) { /** @@ -142,11 +142,11 @@ export class LocalTime { } /** - * Create a local time object from the given standard JavaScript `Date` and optional nanoseconds. + * Create a {@link LocalTime} object from the given standard JavaScript `Date` and optional nanoseconds. * Year, month, day and time zone offset components of the given date are ignored. - * @param {global.Date} standardDate the standard JavaScript date to convert. - * @param {Integer|number|undefined} nanosecond the optional amount of nanoseconds. - * @return {LocalTime} new local time. + * @param {global.Date} standardDate - The standard JavaScript date to convert. + * @param {Integer|number|undefined} nanosecond - The optional amount of nanoseconds. + * @return {LocalTime} New LocalTime. */ static fromStandardDate (standardDate, nanosecond) { verifyStandardDateAndNanos(standardDate, nanosecond) @@ -189,16 +189,16 @@ export function isLocalTime (obj) { /** * Represents an instant capturing the time of day, and the timezone offset in seconds, but not the date. - * Created `Time` objects are frozen with `Object.freeze()` in constructor and thus immutable. + * Created {@link Time} objects are frozen with `Object.freeze()` in constructor and thus immutable. */ export class Time { /** * @constructor - * @param {Integer|number} hour the hour for the new local time. - * @param {Integer|number} minute the minute for the new local time. - * @param {Integer|number} second the second for the new local time. - * @param {Integer|number} nanosecond the nanosecond for the new local time. - * @param {Integer|number} timeZoneOffsetSeconds the time zone offset in seconds. Value represents the difference, in seconds, from UTC to local time. + * @param {Integer|number} hour - The hour for the new local time. + * @param {Integer|number} minute - The minute for the new local time. + * @param {Integer|number} second - The second for the new local time. + * @param {Integer|number} nanosecond - The nanosecond for the new local time. + * @param {Integer|number} timeZoneOffsetSeconds - The time zone offset in seconds. Value represents the difference, in seconds, from UTC to local time. * This is different from standard JavaScript `Date.getTimezoneOffset()` which is the difference, in minutes, from local time to UTC. */ constructor (hour, minute, second, nanosecond, timeZoneOffsetSeconds) { @@ -234,11 +234,11 @@ export class Time { } /** - * Create a time object from the given standard JavaScript `Date` and optional nanoseconds. + * Create a {@link Time} object from the given standard JavaScript `Date` and optional nanoseconds. * Year, month and day components of the given date are ignored. - * @param {global.Date} standardDate the standard JavaScript date to convert. - * @param {Integer|number|undefined} nanosecond the optional amount of nanoseconds. - * @return {Time} new time. + * @param {global.Date} standardDate - The standard JavaScript date to convert. + * @param {Integer|number|undefined} nanosecond - The optional amount of nanoseconds. + * @return {Time} New Time. */ static fromStandardDate (standardDate, nanosecond) { verifyStandardDateAndNanos(standardDate, nanosecond) @@ -284,14 +284,14 @@ export function isTime (obj) { /** * Represents an instant capturing the date, but not the time, nor the timezone. - * Created `Date` objects are frozen with `Object.freeze()` in constructor and thus immutable. + * Created {@link Date} objects are frozen with `Object.freeze()` in constructor and thus immutable. */ export class Date { /** * @constructor - * @param {Integer|number} year the year for the new local date. - * @param {Integer|number} month the month for the new local date. - * @param {Integer|number} day the day for the new local date. + * @param {Integer|number} year - The year for the new local date. + * @param {Integer|number} month - The month for the new local date. + * @param {Integer|number} day - The day for the new local date. */ constructor (year, month, day) { /** @@ -313,10 +313,10 @@ export class Date { } /** - * Create a date object from the given standard JavaScript `Date`. + * Create a {@link Date} object from the given standard JavaScript `Date`. * Hour, minute, second, millisecond and time zone offset components of the given date are ignored. - * @param {global.Date} standardDate the standard JavaScript date to convert. - * @return {Date} new date. + * @param {global.Date} standardDate - The standard JavaScript date to convert. + * @return {Date} New Date. */ static fromStandardDate (standardDate) { verifyStandardDateAndNanos(standardDate, null) @@ -344,7 +344,7 @@ Object.defineProperty( /** * Test if given object is an instance of {@link Date} class. - * @param {Object} obj the object to test. + * @param {Object} obj - The object to test. * @return {boolean} `true` if given object is a {@link Date}, `false` otherwise. */ export function isDate (obj) { @@ -353,18 +353,18 @@ export function isDate (obj) { /** * Represents an instant capturing the date and the time, but not the timezone. - * Created `LocalDateTime` objects are frozen with `Object.freeze()` in constructor and thus immutable. + * Created {@link LocalDateTime} objects are frozen with `Object.freeze()` in constructor and thus immutable. */ export class LocalDateTime { /** * @constructor - * @param {Integer|number} year the year for the new local date. - * @param {Integer|number} month the month for the new local date. - * @param {Integer|number} day the day for the new local date. - * @param {Integer|number} hour the hour for the new local time. - * @param {Integer|number} minute the minute for the new local time. - * @param {Integer|number} second the second for the new local time. - * @param {Integer|number} nanosecond the nanosecond for the new local time. + * @param {Integer|number} year - The year for the new local date. + * @param {Integer|number} month - The month for the new local date. + * @param {Integer|number} day - The day for the new local date. + * @param {Integer|number} hour - The hour for the new local time. + * @param {Integer|number} minute - The minute for the new local time. + * @param {Integer|number} second - The second for the new local time. + * @param {Integer|number} nanosecond - The nanosecond for the new local time. */ constructor (year, month, day, hour, minute, second, nanosecond) { /** @@ -406,11 +406,11 @@ export class LocalDateTime { } /** - * Create a local date-time object from the given standard JavaScript `Date` and optional nanoseconds. + * Create a {@link LocalDateTime} object from the given standard JavaScript `Date` and optional nanoseconds. * Time zone offset component of the given date is ignored. - * @param {global.Date} standardDate the standard JavaScript date to convert. - * @param {Integer|number|undefined} nanosecond the optional amount of nanoseconds. - * @return {LocalDateTime} new local date-time. + * @param {global.Date} standardDate - The standard JavaScript date to convert. + * @param {Integer|number|undefined} nanosecond - The optional amount of nanoseconds. + * @return {LocalDateTime} New LocalDateTime. */ static fromStandardDate (standardDate, nanosecond) { verifyStandardDateAndNanos(standardDate, nanosecond) @@ -450,7 +450,7 @@ Object.defineProperty( /** * Test if given object is an instance of {@link LocalDateTime} class. - * @param {Object} obj the object to test. + * @param {Object} obj - The object to test. * @return {boolean} `true` if given object is a {@link LocalDateTime}, `false` otherwise. */ export function isLocalDateTime (obj) { @@ -459,22 +459,22 @@ export function isLocalDateTime (obj) { /** * Represents an instant capturing the date, the time and the timezone identifier. - * Created `DateTime` objects are frozen with `Object.freeze()` in constructor and thus immutable. + * Created {@ DateTime} objects are frozen with `Object.freeze()` in constructor and thus immutable. */ export class DateTime { /** * @constructor - * @param {Integer|number} year the year for the new date-time. - * @param {Integer|number} month the month for the new date-time. - * @param {Integer|number} day the day for the new date-time. - * @param {Integer|number} hour the hour for the new date-time. - * @param {Integer|number} minute the minute for the new date-time. - * @param {Integer|number} second the second for the new date-time. - * @param {Integer|number} nanosecond the nanosecond for the new date-time. - * @param {Integer|number} timeZoneOffsetSeconds the time zone offset in seconds. Either this argument or `timeZoneId` should be defined. + * @param {Integer|number} year - The year for the new date-time. + * @param {Integer|number} month - The month for the new date-time. + * @param {Integer|number} day - The day for the new date-time. + * @param {Integer|number} hour - The hour for the new date-time. + * @param {Integer|number} minute - The minute for the new date-time. + * @param {Integer|number} second - The second for the new date-time. + * @param {Integer|number} nanosecond - The nanosecond for the new date-time. + * @param {Integer|number} timeZoneOffsetSeconds - The time zone offset in seconds. Either this argument or `timeZoneId` should be defined. * Value represents the difference, in seconds, from UTC to local time. * This is different from standard JavaScript `Date.getTimezoneOffset()` which is the difference, in minutes, from local time to UTC. - * @param {string|null} timeZoneId the time zone id for the new date-time. Either this argument or `timeZoneOffsetSeconds` should be defined. + * @param {string|null} timeZoneId - The time zone id for the new date-time. Either this argument or `timeZoneOffsetSeconds` should be defined. */ constructor ( year, @@ -548,10 +548,10 @@ export class DateTime { } /** - * Create a date-time object from the given standard JavaScript `Date` and optional nanoseconds. - * @param {global.Date} standardDate the standard JavaScript date to convert. - * @param {Integer|number|undefined} nanosecond the optional amount of nanoseconds. - * @return {DateTime} new date-time. + * Create a {@link DateTime} object from the given standard JavaScript `Date` and optional nanoseconds. + * @param {global.Date} standardDate - The standard JavaScript date to convert. + * @param {Integer|number|undefined} nanosecond - The optional amount of nanoseconds. + * @return {DateTime} New DateTime. */ static fromStandardDate (standardDate, nanosecond) { verifyStandardDateAndNanos(standardDate, nanosecond) @@ -597,7 +597,7 @@ Object.defineProperty( /** * Test if given object is an instance of {@link DateTime} class. - * @param {Object} obj the object to test. + * @param {Object} obj - The object to test. * @return {boolean} `true` if given object is a {@link DateTime}, `false` otherwise. */ export function isDateTime (obj) {