Documentation fixes (#1236)

Standardizes the usage of the link tag in deprecation messages. Adds a note concerning the use of CALL {} IN TRANSACTIONS in explicit transactions
neo4j · Nov 8, 2024 · 0ebd3b5 · 0ebd3b5
1 parent 291df7e
commit 0ebd3b5
Show file tree

Hide file tree

Showing 9 changed files with 33 additions and 17 deletions.
diff --git a/packages/core/src/client-certificate.ts b/packages/core/src/client-certificate.ts
@@ -74,8 +74,8 @@ export default class ClientCertificate {
 /**
  * Provides a client certificate to the driver for mutual TLS.
  *
- * The driver will call {@link ClientCertificateProvider#hasUpdate()} to check if the client wants to update the certificate.
- * If so, it will call {@link ClientCertificateProvider#getCertificate()} to get the new certificate.
+ * The driver will call {@link ClientCertificateProvider#hasUpdate} to check if the client wants to update the certificate.
+ * If so, it will call {@link ClientCertificateProvider#getClientCertificate} to get the new certificate.
  *
  * The certificate is only used as a second factor for authentication authenticating the client.
  * The DMBS user still needs to authenticate with an authentication token.
@@ -103,7 +103,7 @@ export class ClientCertificateProvider {
   /**
    * Returns the certificate to use for new connections.
    *
-   * Will be called by the driver after {@link ClientCertificateProvider#hasUpdate()} returned true
+   * Will be called by the driver after {@link ClientCertificateProvider#hasUpdate} returned true
    * or when the driver establishes the first connection.
    *
    * @returns {Promise<ClientCertificate>|ClientCertificate} the certificate to use for new connections

diff --git a/packages/core/src/session.ts b/packages/core/src/session.ts
@@ -351,7 +351,7 @@ class Session {
   /**
    * Return the bookmarks received following the last completed {@link Transaction}.
    *
-   * @deprecated This method will be removed in version 6.0. Please, use Session#lastBookmarks instead.
+   * @deprecated This method will be removed in version 6.0. Please, use {@link Session#lastBookmarks} instead.
    *
    * @return {string[]} A reference to a previous transaction.
    * @see {@link Session#lastBookmarks}
@@ -385,7 +385,7 @@ 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.
    *
-   * @deprecated This method will be removed in version 6.0. Please, use Session#executeRead instead.
+   * @deprecated This method will be removed in version 6.0. Please, use {@link Session#executeRead} instead.
    *
    * @param {function(tx: Transaction): Promise} transactionWork - Callback that executes operations against
    * a given {@link Transaction}.
@@ -410,7 +410,7 @@ 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.
    *
-   * @deprecated This method will be removed in version 6.0. Please, use Session#executeWrite instead.
+   * @deprecated This method will be removed in version 6.0. Please, use {@link Session#executeWrite} instead.
    *
    * @param {function(tx: Transaction): Promise} transactionWork - Callback that executes operations against
    * a given {@link Transaction}.
@@ -446,6 +446,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.
    *
+   * NOTE: Because it is an explicit transaction from the server point of view, Cypher queries using
+   * "CALL {} IN TRANSACTIONS" or the older "USING PERIODIC COMMIT" construct will not work (call
+   * {@link Session#run} for these).
+   *
    * @param {function(tx: ManagedTransaction): 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.
@@ -468,6 +472,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.
    *
+   * NOTE: Because it is an explicit transaction from the server point of view, Cypher queries using
+   * "CALL {} IN TRANSACTIONS" or the older "USING PERIODIC COMMIT" construct will not work (call
+   * {@link Session#run} for these).
+   *
    * @param {function(tx: ManagedTransaction): 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.

diff --git a/packages/core/src/transaction-promise.ts b/packages/core/src/transaction-promise.ts
@@ -27,7 +27,7 @@ import { TxConfig } from './internal/tx-config'
 import NotificationFilter from './notification-filter'
 
 /**
- * Represents a {@link Promise<Transaction>} object and a {@link Transaction} object.
+ * Represents a Promise<{@link Transaction}> object and a {@link Transaction} object.
  *
  * Resolving this object promise verifies the result of the transaction begin and returns the {@link Transaction} object in case of success.
  *

diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
@@ -298,7 +298,7 @@ export class Config {
     this.resolver = undefined
 
     /**
-     * Configure filter for Notification objects returned in {@Link ResultSummary#notifications}.
+     * Configure filter for Notification objects returned in {@link ResultSummary#notifications}.
      *
      * See {@link SessionConfig#notificationFilter} for usage instructions.
      *

diff --git a/packages/neo4j-driver-deno/lib/core/client-certificate.ts b/packages/neo4j-driver-deno/lib/core/client-certificate.ts
@@ -74,8 +74,8 @@ export default class ClientCertificate {
 /**
  * Provides a client certificate to the driver for mutual TLS.
  *
- * The driver will call {@link ClientCertificateProvider#hasUpdate()} to check if the client wants to update the certificate.
- * If so, it will call {@link ClientCertificateProvider#getCertificate()} to get the new certificate.
+ * The driver will call {@link ClientCertificateProvider#hasUpdate} to check if the client wants to update the certificate.
+ * If so, it will call {@link ClientCertificateProvider#getClientCertificate} to get the new certificate.
  *
  * The certificate is only used as a second factor for authentication authenticating the client.
  * The DMBS user still needs to authenticate with an authentication token.
@@ -103,7 +103,7 @@ export class ClientCertificateProvider {
   /**
    * Returns the certificate to use for new connections.
    *
-   * Will be called by the driver after {@link ClientCertificateProvider#hasUpdate()} returned true
+   * Will be called by the driver after {@link ClientCertificateProvider#hasUpdate} returned true
    * or when the driver establishes the first connection.
    *
    * @returns {Promise<ClientCertificate>|ClientCertificate} the certificate to use for new connections

diff --git a/packages/neo4j-driver-deno/lib/core/session.ts b/packages/neo4j-driver-deno/lib/core/session.ts
@@ -351,7 +351,7 @@ class Session {
   /**
    * Return the bookmarks received following the last completed {@link Transaction}.
    *
-   * @deprecated This method will be removed in version 6.0. Please, use Session#lastBookmarks instead.
+   * @deprecated This method will be removed in version 6.0. Please, use {@link Session#lastBookmarks} instead.
    *
    * @return {string[]} A reference to a previous transaction.
    * @see {@link Session#lastBookmarks}
@@ -385,7 +385,7 @@ 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.
    *
-   * @deprecated This method will be removed in version 6.0. Please, use Session#executeRead instead.
+   * @deprecated This method will be removed in version 6.0. Please, use {@link Session#executeRead} instead.
    *
    * @param {function(tx: Transaction): Promise} transactionWork - Callback that executes operations against
    * a given {@link Transaction}.
@@ -410,7 +410,7 @@ 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.
    *
-   * @deprecated This method will be removed in version 6.0. Please, use Session#executeWrite instead.
+   * @deprecated This method will be removed in version 6.0. Please, use {@link Session#executeWrite} instead.
    *
    * @param {function(tx: Transaction): Promise} transactionWork - Callback that executes operations against
    * a given {@link Transaction}.
@@ -446,6 +446,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.
    *
+   * NOTE: Because it is an explicit transaction from the server point of view, Cypher queries using
+   * "CALL {} IN TRANSACTIONS" or the older "USING PERIODIC COMMIT" construct will not work (call
+   * {@link Session#run} for these).
+   *
    * @param {function(tx: ManagedTransaction): 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.
@@ -468,6 +472,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.
    *
+   * NOTE: Because it is an explicit transaction from the server point of view, Cypher queries using
+   * "CALL {} IN TRANSACTIONS" or the older "USING PERIODIC COMMIT" construct will not work (call
+   * {@link Session#run} for these).
+   *
    * @param {function(tx: ManagedTransaction): 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.

diff --git a/packages/neo4j-driver-deno/lib/core/transaction-promise.ts b/packages/neo4j-driver-deno/lib/core/transaction-promise.ts
@@ -27,7 +27,7 @@ import { TxConfig } from './internal/tx-config.ts'
 import NotificationFilter from './notification-filter.ts'
 
 /**
- * Represents a {@link Promise<Transaction>} object and a {@link Transaction} object.
+ * Represents a Promise<{@link Transaction}> object and a {@link Transaction} object.
  *
  * Resolving this object promise verifies the result of the transaction begin and returns the {@link Transaction} object in case of success.
  *

diff --git a/packages/neo4j-driver-deno/lib/core/types.ts b/packages/neo4j-driver-deno/lib/core/types.ts
@@ -298,7 +298,7 @@ export class Config {
     this.resolver = undefined
 
     /**
-     * Configure filter for Notification objects returned in {@Link ResultSummary#notifications}.
+     * Configure filter for Notification objects returned in {@link ResultSummary#notifications}.
      *
      * See {@link SessionConfig#notificationFilter} for usage instructions.
      *

diff --git a/packages/neo4j-driver/src/result-rx.js b/packages/neo4j-driver/src/result-rx.js
@@ -121,7 +121,7 @@ export default class RxResult {
    *
    * This method won't need to be called in normal stream operation. It only applies to the case when the stream is paused.
    *
-   * This method is method won't start the consuming records if the ${@link records()} stream didn't get subscribed.
+   * This method is method won't start the consuming records if the {@link records} stream didn't get subscribed.
    * @experimental
    * @returns {Promise<void>} - A promise that resolves when the stream is resumed.
    */