Couple JSDoc markup improvements

Author: lutovich

src/v1/driver.js

@@ -33,14 +33,14 @@ const DEFAULT_MAX_CONNECTION_LIFETIME = 60 * 60 * 1000; // 1 hour
 
 /**
  * Constant that represents read session access mode.
- * Should be used like this: <code>driver.session(READ)</code>.
+ * Should be used like this: `driver.session(neo4j.session.READ)`.
  * @type {string}
  */
 const READ = 'READ';
 
 /**
  * Constant that represents write session access mode.
- * Should be used like this: <code>driver.session(WRITE)</code>.
+ * Should be used like this: `driver.session(neo4j.session.WRITE)`.
  * @type {string}
  */
 const WRITE = 'WRITE';

src/v1/index.js

@@ -69,9 +69,9 @@ const auth = {
 const USER_AGENT = "neo4j-javascript/" + VERSION;
 
 /**
- * Object containing predefined logging configurations. These are expected to be used as values of the driver config's <code>logging</code> property.
- * @property {function(level: ?string): object} console the function to create a logging config that prints all messages to <code>console.log</code> with
- * timestamp, level and message. It takes an optional <code>level</code> parameter which represents the maximum log level to be logged. Default value is 'info'.
+ * 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 => {
@@ -136,7 +136,7 @@ const logging = {
  *
  *       // The max number of connections that are allowed idle in the pool at any time.
  *       // Connection will be destroyed if this threshold is exceeded.
- *       // <b>Deprecated:</b> please use <code>maxConnectionPoolSize</code> instead.
+ *       // **Deprecated:** please use `maxConnectionPoolSize` instead.
  *       connectionPoolSize: 100,
  *
  *       // The maximum total number of connections allowed to be managed by the connection pool, per host.
@@ -158,15 +158,15 @@ const logging = {
  *       connectionAcquisitionTimeout: 60000, // 1 minute
  *
  *       // Specify the maximum time in milliseconds transactions are allowed to retry via
- *       // <code>Session#readTransaction()</code> and <code>Session#writeTransaction()</code> functions.
+ *       // `Session#readTransaction()` and `Session#writeTransaction()` functions.
  *       // These functions will retry the given unit of work on `ServiceUnavailable`, `SessionExpired` and transient
  *       // errors with exponential backoff using initial delay of 1 second.
  *       // Default value is 30000 which is 30 seconds.
  *       maxTransactionRetryTime: 30000, // 30 seconds
  *
  *       // Provide an alternative load balancing strategy for the routing driver to use.
  *       // Driver uses "least_connected" by default.
- *       // <b>Note:</b> We are experimenting with different strategies. This could be removed in the next minor
+ *       // **Note:** We are experimenting with different strategies. This could be removed in the next minor
  *       // version.
  *       loadBalancingStrategy: "least_connected" | "round_robin",
  *
@@ -177,27 +177,27 @@ const logging = {
  *
  *       // Make this driver always return native JavaScript numbers for integer values, instead of the
  *       // dedicated {@link Integer} class. Values that do not fit in native number bit range will be represented as
- *       // <code>Number.NEGATIVE_INFINITY</code> or <code>Number.POSITIVE_INFINITY</code>.
- *       // <b>Warning:</b> It is not always safe to enable this setting when JavaScript applications are not the only ones
+ *       // `Number.NEGATIVE_INFINITY` or `Number.POSITIVE_INFINITY`.
+ *       // **Warning:** ResultSummary It is not always safe to enable this setting when JavaScript applications are not the only ones
  *       // interacting with the database. Stored numbers might in such case be not representable by native
  *       // {@link Number} type and thus driver will return lossy values. This might also happen when data was
  *       // initially imported using neo4j import tool and contained numbers larger than
- *       // <code>Number.MAX_SAFE_INTEGER</code>. Driver will then return positive infinity, which is lossy.
- *       // Default value for this option is <code>false</code> because native JavaScript numbers might result
+ *       // `Number.MAX_SAFE_INTEGER`. Driver will then return positive infinity, which is lossy.
+ *       // Default value for this option is `false` because native JavaScript numbers might result
  *       // in loss of precision in the general case.
  *       disableLosslessIntegers: false,
  *
- *       // Specify the logging configuration for the driver. Object should have two properties <code>level</code> and <code>logger</code>.
+ *       // Specify the logging configuration for the driver. Object should have two properties `level` and `logger`.
  *       //
- *       // Property <code>level</code> represents the logging level which should be one of: 'error', 'warn', 'info' or 'debug'. This property is optional and
+ *       // Property `level` represents the logging level which should be one of: 'error', 'warn', 'info' or 'debug'. This property is optional and
  *       // its default value is 'info'. Levels have priorities: 'error': 0, 'warn': 1, 'info': 2, 'debug': 3. Enabling a certain level also enables all
  *       // levels with lower priority. For example: 'error', 'warn' and 'info' will be logged when 'info' level is configured.
  *       //
- *       // Property <code>logger</code> represents the logging function which will be invoked for every log call with an acceptable level. The function should
- *       // take two string arguments <code>level</code> and <code>message</code>. The function should not execute any blocking or long-running operations
+ *       // Property `logger` represents the logging function which will be invoked for every log call with an acceptable level. The function should
+ *       // take two string arguments `level` and `message`. The function should not execute any blocking or long-running operations
  *       // because it is often executed on a hot path.
  *       //
- *       // No logging is done by default. See <code>neo4j.logging</code> object that contains predefined logging implementations.
+ *       // No logging is done by default. See `neo4j.logging` object that contains predefined logging implementations.
  *       logging: {
  *         level: 'info',
  *         logger: (level, message) => console.log(level + ' ' + message)

src/v1/integer.js

@@ -26,9 +26,9 @@ import {newError} from './error';
 /**
  * Constructs a 64 bit two's-complement integer, given its low and high 32 bit values as *signed* integers.
  * See exported functions for more convenient ways of operating integers.
- * Use <code>int()</code> function to create new integers, <code>isInt()</code> to check if given object is integer,
- * <code>inSafeRange()</code> to check if it is safe to convert given value to native number,
- * <code>toNumber()</code> and <code>toString()</code> to convert given integer to number or string respectively.
+ * Use `int()` function to create new integers, `isInt()` to check if given object is integer,
+ * `inSafeRange()` to check if it is safe to convert given value to native number,
+ * `toNumber()` and `toString()` to convert given integer to number or string respectively.
  * @access public
  * @exports Integer
  * @class A Integer class for representing a 64 bit two's-complement integer value.

src/v1/internal/bookmark.js

@@ -42,15 +42,15 @@ export default class Bookmark {
 
   /**
    * Check if the given bookmark is meaningful and can be send to the database.
-   * @return {boolean} returns <code>true</code> bookmark has a value, <code>false</code> otherwise.
+   * @return {boolean} returns `true` bookmark has a value, `false` otherwise.
    */
   isEmpty() {
     return this._maxValue === null;
   }
 
   /**
    * Get maximum value of this bookmark as string.
-   * @return {string|null} the maximum value or <code>null</code> if it is not defined.
+   * @return {string|null} the maximum value or `null` if it is not defined.
    */
   maxBookmarkAsString() {
     return this._maxValue;

src/v1/internal/ch-websocket.js

@@ -265,23 +265,23 @@ function determineWebSocketScheme(config, protocolSupplier) {
 
 /**
  * @param {ChannelConfig} config - configuration for the channel.
- * @return {boolean} <code>true</code> if encryption enabled in the config, <code>false</code> otherwise.
+ * @return {boolean} `true` if encryption enabled in the config, `false` otherwise.
  */
 function isEncryptionExplicitlyTurnedOn(config) {
   return config.encrypted === true || config.encrypted === ENCRYPTION_ON;
 }
 
 /**
  * @param {ChannelConfig} config - configuration for the channel.
- * @return {boolean} <code>true</code> if encryption disabled in the config, <code>false</code> otherwise.
+ * @return {boolean} `true` if encryption disabled in the config, `false` otherwise.
  */
 function isEncryptionExplicitlyTurnedOff(config) {
   return config.encrypted === false || config.encrypted === ENCRYPTION_OFF;
 }
 
 /**
  * @param {function(): string} protocolSupplier - function that detects protocol of the web page.
- * @return {boolean} <code>true</code> if protocol returned by the given function is secure, <code>false</code> otherwise.
+ * @return {boolean} `true` if protocol returned by the given function is secure, `false` otherwise.
  */
 function isProtocolSecure(protocolSupplier) {
   const protocol = typeof protocolSupplier === 'function' ? protocolSupplier() : '';

src/v1/internal/connection.js

@@ -196,7 +196,7 @@ export default class Connection {
    * Write a message to the network channel.
    * @param {RequestMessage} message the message to write.
    * @param {StreamObserver} observer the response observer.
-   * @param {boolean} flush <code>true</code> if flush should happen after the message is written to the buffer.
+   * @param {boolean} flush `true` if flush should happen after the message is written to the buffer.
    */
   write(message, observer, flush) {
     const queued = this._queueObserver(observer);

src/v1/internal/load-balancing-strategy.js

@@ -25,7 +25,7 @@ export default class LoadBalancingStrategy {
   /**
    * Select next most appropriate reader from the list of given readers.
    * @param {string[]} knownReaders an array of currently known readers to select from.
-   * @return {string} most appropriate reader or <code>null</code> if given array is empty.
+   * @return {string} most appropriate reader or `null` if given array is empty.
    */
   selectReader(knownReaders) {
     throw new Error('Abstract function');
@@ -34,7 +34,7 @@ export default class LoadBalancingStrategy {
   /**
    * Select next most appropriate writer from the list of given writers.
    * @param {string[]} knownWriters an array of currently known writers to select from.
-   * @return {string} most appropriate writer or <code>null</code> if given array is empty.
+   * @return {string} most appropriate writer or `null` if given array is empty.
    */
   selectWriter(knownWriters) {
     throw new Error('Abstract function');

src/v1/internal/logger.js

@@ -72,7 +72,7 @@ class Logger {
 
   /**
    * Check if error logging is enabled, i.e. it is not a no-op implementation.
-   * @return {boolean} <code>true</code> when enabled, <code>false</code> otherwise.
+   * @return {boolean} `true` when enabled, `false` otherwise.
    */
   isErrorEnabled() {
     return isLevelEnabled(this._level, ERROR);
@@ -90,7 +90,7 @@ class Logger {
 
   /**
    * Check if warn logging is enabled, i.e. it is not a no-op implementation.
-   * @return {boolean} <code>true</code> when enabled, <code>false</code> otherwise.
+   * @return {boolean} `true` when enabled, `false` otherwise.
    */
   isWarnEnabled() {
     return isLevelEnabled(this._level, WARN);
@@ -108,7 +108,7 @@ class Logger {
 
   /**
    * Check if info logging is enabled, i.e. it is not a no-op implementation.
-   * @return {boolean} <code>true</code> when enabled, <code>false</code> otherwise.
+   * @return {boolean} `true` when enabled, `false` otherwise.
    */
   isInfoEnabled() {
     return isLevelEnabled(this._level, INFO);
@@ -126,7 +126,7 @@ class Logger {
 
   /**
    * Check if debug logging is enabled, i.e. it is not a no-op implementation.
-   * @return {boolean} <code>true</code> when enabled, <code>false</code> otherwise.
+   * @return {boolean} `true` when enabled, `false` otherwise.
    */
   isDebugEnabled() {
     return isLevelEnabled(this._level, DEBUG);
@@ -184,7 +184,7 @@ const noOpLogger = new NoOpLogger();
  * Check if the given logging level is enabled.
  * @param {string} configuredLevel the configured level.
  * @param {string} targetLevel the level to check.
- * @return {boolean} value of <code>true</code> when enabled, <code>false</code> otherwise.
+ * @return {boolean} value of `true` when enabled, `false` otherwise.
  */
 function isLevelEnabled(configuredLevel, targetLevel) {
   return levels[configuredLevel] >= levels[targetLevel];

src/v1/internal/pool.js

@@ -121,7 +121,7 @@ class Pool {
   /**
    * Check if this pool contains resources for the given key.
    * @param {string} key the resource key to check.
-   * @return {boolean} <code>true</code> when pool contains entries for the given key, <code>false</code> otherwise.
+   * @return {boolean} `true` when pool contains entries for the given key, <code>false</code> otherwise.
    */
   has(key) {
     return (key in this._pools);

src/v1/internal/routing-table.js

@@ -57,8 +57,7 @@ export default class RoutingTable {
   /**
    * Check if this routing table is fresh to perform the required operation.
    * @param {string} accessMode the type of operation. Allowed values are {@link READ} and {@link WRITE}.
-   * @return {boolean} <code>true</code> when this table contains servers to serve the required operation,
-   * <code>false</code> otherwise.
+   * @return {boolean} `true` when this table contains servers to serve the required operation, `false` otherwise.
    */
   isStaleFor(accessMode) {
     return this.expirationTime.lessThan(Date.now()) ||

src/v1/internal/temporal-util.js

@@ -27,7 +27,7 @@ import {newError} from '../error';
 
   It is based on a library called ThreeTen (https://github.com/ThreeTen/threetenbp) which was derived
   from JSR-310 reference implementation previously hosted on GitHub. Code uses `Integer` type everywhere
-  to correctly handle large integer values that are greater than <code>Number.MAX_SAFE_INTEGER</code>.
+  to correctly handle large integer values that are greater than `Number.MAX_SAFE_INTEGER`.
 
   Please consult either ThreeTen or js-joda (https://github.com/js-joda/js-joda) when working with the
   conversion functions.
@@ -416,7 +416,7 @@ function localTimeToSecondOfDay(hour, minute, second) {
 /**
  * Check if given year is a leap year. Uses algorithm described here {@link https://en.wikipedia.org/wiki/Leap_year#Algorithm}.
  * @param {Integer|number|string} year the year to check. Will be converted to {@link Integer} for all calculations.
- * @return {boolean} <code>true</code> if given year is a leap year, <code>false</code> otherwise.
+ * @return {boolean} `true` if given year is a leap year, `false` otherwise.
  */
 function isLeapYear(year) {
   year = int(year);

src/v1/result-summary.js

@@ -20,7 +20,7 @@
 import {isInt} from './integer';
 
 /**
-  * A ResultSummary instance contains structured metadata for a {Result}.
+ * A ResultSummary instance contains structured metadata for a {@link Result}.
   * @access public
   */
 class ResultSummary {

src/v1/result.js

@@ -30,7 +30,7 @@ const DEFAULT_ON_COMPLETED = summary => {
  * A stream of {@link Record} representing the result of a statement.
  * Can be consumed eagerly as {@link Promise} resolved with array of records and {@link ResultSummary}
  * summary, or rejected with error that contains {@link string} code and {@link string} message.
- * Alternatively can be consumed lazily using <code>Result.subscribe()</code> function.
+ * Alternatively can be consumed lazily using {@link Result#subscribe} function.
  * @access public
  */
 class Result {
@@ -79,7 +79,7 @@ class Result {
 
   /**
    * Waits for all results and calls the passed in function with the results.
-   * Cannot be combined with the <code>Result.subscribe()</code> function.
+   * Cannot be combined with the {@link Result#subscribe} function.
    *
    * @param {function(result: {records:Array<Record>, summary: ResultSummary})} onFulfilled - function to be called
    * when finished.

src/v1/session.js

@@ -72,7 +72,7 @@ class Session {
 
   /**
    * Run Cypher statement
-   * Could be called with a statement object i.e.: {text: "MATCH ...", parameters: {param: 1}}
+   * Could be called with a statement object i.e.: `{text: "MATCH ...", parameters: {param: 1}}`
    * or with the statement and parameters as separate arguments.
    * @param {mixed} statement - Cypher statement to execute
    * @param {Object} parameters - Map with parameters to use in statement
@@ -167,7 +167,7 @@ class Session {
    * Transaction will automatically be committed unless the given function throws or returns a rejected promise.
    * Some failures of the given function or the commit itself will be retried with exponential backoff with initial
    * delay of 1 second and maximum retry time of 30 seconds. Maximum retry time is configurable via driver config's
-   * <code>maxTransactionRetryTime</code> property in milliseconds.
+   * `maxTransactionRetryTime` property in milliseconds.
    *
    * @param {function(tx: Transaction): Promise} transactionWork - callback that executes operations against
    * a given {@link Transaction}.
@@ -186,7 +186,7 @@ class Session {
    * Transaction will automatically be committed unless the given function throws or returns a rejected promise.
    * Some failures of the given function or the commit itself will be retried with exponential backoff with initial
    * delay of 1 second and maximum retry time of 30 seconds. Maximum retry time is configurable via driver config's
-   * <code>maxTransactionRetryTime</code> property in milliseconds.
+   * `maxTransactionRetryTime` property in milliseconds.
    *
    * @param {function(tx: Transaction): Promise} transactionWork - callback that executes operations against
    * a given {@link Transaction}.

src/v1/spatial-types.js

@@ -22,16 +22,16 @@ const POINT_IDENTIFIER_PROPERTY = '__isPoint__';
 
 /**
  * Represents a single two or three-dimensional point in a particular coordinate reference system.
- * Created <code>Point</code> objects are frozen with {@link Object#freeze()} in constructor and thus immutable.
+ * Created `Point` objects are frozen with `Object.freeze()` in constructor and thus immutable.
  */
 export class Point {
 
   /**
    * @constructor
    * @param {Integer|number} srid the coordinate reference system identifier.
-   * @param {number} x the <code>x</code> coordinate of the point.
-   * @param {number} y the <code>y</code> coordinate of the point.
-   * @param {number} [z=undefined] the <code>y</code> coordinate of the point or <code>undefined</code> if point has 2 dimensions.
+   * @param {number} x the `x` coordinate of the point.
+   * @param {number} y the `y` coordinate of the point.
+   * @param {number} [z=undefined] the `y` coordinate of the point or `undefined` if point has 2 dimensions.
    */
   constructor(srid, x, y, z) {
     this.srid = assertNumberOrInteger(srid, 'SRID');
@@ -61,7 +61,7 @@ Object.defineProperty(Point.prototype, POINT_IDENTIFIER_PROPERTY, {
 /**
  * Test if given object is an instance of {@link Point} class.
  * @param {object} obj the object to test.
- * @return {boolean} <code>true</code> if given object is a {@link Point}, <code>false</code> otherwise.
+ * @return {boolean} `true` if given object is a {@link Point}, `false` otherwise.
  */
 export function isPoint(obj) {
   return (obj && obj[POINT_IDENTIFIER_PROPERTY]) === true;