Documentation fixes (#1236)

MaxAake · web-flow · commit 0ebd3b5d4f51 · 2024-11-08T13:07:20.000+01:00
Standardizes the usage of the link tag in deprecation messages.

Adds a note concerning the use of CALL {} IN TRANSACTIONS in explicit transactions
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.
    */

Original file line number	Diff line number	Diff line change
`@@ -74,8 +74,8 @@ export default class ClientCertificate {`
`74`	`74`	`/**`
`75`	`75`	`* Provides a client certificate to the driver for mutual TLS.`
`76`	`76`	`*`
`77`		`- * The driver will call {@link ClientCertificateProvider#hasUpdate()} to check if the client wants to update the certificate.`
`78`		`- * If so, it will call {@link ClientCertificateProvider#getCertificate()} to get the new certificate.`
	`77`	`+ * The driver will call {@link ClientCertificateProvider#hasUpdate} to check if the client wants to update the certificate.`
	`78`	`+ * If so, it will call {@link ClientCertificateProvider#getClientCertificate} to get the new certificate.`
`79`	`79`	`*`
`80`	`80`	`* The certificate is only used as a second factor for authentication authenticating the client.`
`81`	`81`	`* The DMBS user still needs to authenticate with an authentication token.`
`@@ -103,7 +103,7 @@ export class ClientCertificateProvider {`
`103`	`103`	`/**`
`104`	`104`	`* Returns the certificate to use for new connections.`
`105`	`105`	`*`
`106`		`- * Will be called by the driver after {@link ClientCertificateProvider#hasUpdate()} returned true`
	`106`	`+ * Will be called by the driver after {@link ClientCertificateProvider#hasUpdate} returned true`
`107`	`107`	`* or when the driver establishes the first connection.`
`108`	`108`	`*`
`109`	`109`	`* @returns {Promise<ClientCertificate>\|ClientCertificate} the certificate to use for new connections`
Original file line number	Diff line number	Diff line change
`@@ -27,7 +27,7 @@ import { TxConfig } from './internal/tx-config'`
`27`	`27`	`import NotificationFilter from './notification-filter'`
`28`	`28`
`29`	`29`	`/**`
`30`		`- * Represents a {@link Promise<Transaction>} object and a {@link Transaction} object.`
	`30`	`+ * Represents a Promise<{@link Transaction}> object and a {@link Transaction} object.`
`31`	`31`	`*`
`32`	`32`	`* Resolving this object promise verifies the result of the transaction begin and returns the {@link Transaction} object in case of success.`
`33`	`33`	`*`
Original file line number	Diff line number	Diff line change
`@@ -298,7 +298,7 @@ export class Config {`
`298`	`298`	`this.resolver = undefined`
`299`	`299`
`300`	`300`	`/**`
`301`		`- * Configure filter for Notification objects returned in {@Link ResultSummary#notifications}.`
	`301`	`+ * Configure filter for Notification objects returned in {@link ResultSummary#notifications}.`
`302`	`302`	`*`
`303`	`303`	`* See {@link SessionConfig#notificationFilter} for usage instructions.`
`304`	`304`	`*`
Original file line number	Diff line number	Diff line change
`@@ -121,7 +121,7 @@ export default class RxResult {`
`121`	`121`	`*`
`122`	`122`	`* This method won't need to be called in normal stream operation. It only applies to the case when the stream is paused.`
`123`	`123`	`*`
`124`		`- * This method is method won't start the consuming records if the ${@link records()} stream didn't get subscribed.`
	`124`	`+ * This method is method won't start the consuming records if the {@link records} stream didn't get subscribed.`
`125`	`125`	`* @experimental`
`126`	`126`	`* @returns {Promise<void>} - A promise that resolves when the stream is resumed.`
`127`	`127`	`*/`