Merge pull request #659 from martin-neotech/4.0-docs-update-2

Docs fixes for 4.0

Author: zhenlineo

driver/src/main/java/org/neo4j/driver/QueryRunner.java

@@ -80,7 +80,7 @@ public interface QueryRunner
      * <pre class="doctest:QueryRunnerDocIT#parameterTest">
      * {@code
      *
-     * Result result = session.run( "MATCH (n) WHERE n.name = {myNameParam} RETURN (n)",
+     * Result result = session.run( "MATCH (n) WHERE n.name = $myNameParam RETURN (n)",
      *                                       Values.parameters( "myNameParam", "Bob" ) );
      * }
      * </pre>
@@ -110,7 +110,7 @@ public interface QueryRunner
      * Map<String, Object> parameters = new HashMap<String, Object>();
      * parameters.put("myNameParam", "Bob");
      *
-     * Result result = session.run( "MATCH (n) WHERE n.name = {myNameParam} RETURN (n)",
+     * Result result = session.run( "MATCH (n) WHERE n.name = $myNameParam RETURN (n)",
      *                                       parameters );
      * }
      * </pre>
@@ -152,7 +152,7 @@ public interface QueryRunner
      * <pre class="doctest:QueryRunnerDocIT#queryObjectTest">
      * {@code
      *
-     * Query query = new Query( "MATCH (n) WHERE n.name=$myNameParam RETURN n.age" );
+     * Query query = new Query( "MATCH (n) WHERE n.name = $myNameParam RETURN n.age" );
      * Result result = session.run( query.withParameters( Values.parameters( "myNameParam", "Bob" )  ) );
      * }
      * </pre>

driver/src/main/java/org/neo4j/driver/Session.java

@@ -50,7 +50,7 @@
  * sessions should be used when an application requires multiple concurrent
  * threads of database work to be carried out.
  *
- * @since 1.0 (Removed async API to {@link AsyncSession} in 2.0)
+ * @since 1.0 (Removed async API to {@link AsyncSession} in 4.0)
  */
 public interface Session extends Resource, QueryRunner
 {
@@ -176,7 +176,7 @@ public interface Session extends Resource, QueryRunner
      * Map<String, Object> parameters = new HashMap<>();
      * parameters.put("myNameParam", "Bob");
      *
-     * Result result = session.run("MATCH (n) WHERE n.name = {myNameParam} RETURN (n)", parameters, config);
+     * Result result = session.run("MATCH (n) WHERE n.name = $myNameParam RETURN (n)", parameters, config);
      * }
      * </pre>
      *
@@ -201,7 +201,7 @@ public interface Session extends Resource, QueryRunner
      *                 .withMetadata(metadata)
      *                 .build();
      *
-     * Query query = new Query("MATCH (n) WHERE n.name=$myNameParam RETURN n.age");
+     * Query query = new Query("MATCH (n) WHERE n.name = $myNameParam RETURN n.age");
      * Result result = session.run(query.withParameters(Values.parameters("myNameParam", "Bob")));
      * }
      * </pre>

driver/src/main/java/org/neo4j/driver/Transaction.java

@@ -28,13 +28,13 @@
  * which ensures in case of any error in try block, the transaction is
  * automatically rolled back on close. Note that <code>ROLLBACK</code> is the
  * default action unless {@link #commit()} is called before closing.
- * {@code
+ * <pre>{@code
  * try(Transaction tx = session.beginTransaction())
  * {
- *     tx.run("CREATE (a:Person {name: {x}})", parameters("x", "Alice"));
+ *     tx.run("CREATE (a:Person {name: $name})", parameters("name", "Alice"));
  *     tx.commit();
  * }
- * }
+ * }</pre>
  * Blocking calls are: {@link #commit()}, {@link #rollback()}, {@link #close()}
  * and various overloads of {@link #run(Query)}.
  *
@@ -53,16 +53,14 @@ public interface Transaction extends Resource, QueryRunner
      * You must call this method before calling {@link #close()} to have your transaction committed.
      * If a transaction is not committed or rolled back before close,
      * the transaction will be rolled back by default in {@link #close}.
-     *
-     Example:
-     *
+     * <pre>Example:
      * {@code
      * try(Transaction tx = session.beginTransaction() )
      * {
-     *     tx.run("CREATE (a:Person {name: {x}})", parameters("x", "Alice"));
+     *     tx.run("CREATE (a:Person {name: $name})", parameters("name", "Alice"));
      *     tx.commit();
      * }
-     * }
+     * }</pre>
      */
     void commit();
 
@@ -72,16 +70,14 @@ public interface Transaction extends Resource, QueryRunner
      * After this method has been called, the transaction cannot be committed or rolled back again.
      * If a transaction is not committed or rolled back before close,
      * the transaction will be rolled back by default in {@link #close}.
-     *
-     * Example:
-     *
+     * <pre>Example:
      * {@code
      * try(Transaction tx = session.beginTransaction() )
      * {
-     *     tx.run("CREATE (a:Person {name: {x}})", parameters("x", "Alice"));
+     *     tx.run("CREATE (a:Person {name: $name})", parameters("name", "Alice"));
      *     tx.rollback();
      * }
-     * }
+     * }</pre>
      */
     void rollback();
 
@@ -90,15 +86,13 @@ public interface Transaction extends Resource, QueryRunner
      * If the transaction has been {@link #commit() committed} or {@link #rollback() rolled back},
      * the close is optional and no operation is performed inside.
      * Otherwise, the transaction will be rolled back by default by this method.
-     *
-     * Example:
-     *
+     * <pre>Example:
      * {@code
      * try(Transaction tx = session.beginTransaction() )
      * {
-     *     tx.run("CREATE (a:Person {name: {x}})", parameters("x", "Alice"));
-     * }
+     *     tx.run("CREATE (a:Person {name: $name})", parameters("name", "Alice"));
      * }
+     * }</pre>
      */
     @Override
     void close();

driver/src/main/java/org/neo4j/driver/async/AsyncQueryRunner.java

@@ -58,7 +58,7 @@
  * <p>
  * As noted, most of the time, you will not need to consider this - your writes will
  * always be durably stored as long as you either use the results, explicitly commit
- * {@link AsyncTransaction transactions} or close the session you used using {@link AsyncSession#closeAsync()}}.
+ * {@link AsyncTransaction transactions} or close the session you used using {@link AsyncSession#closeAsync()}.
  * <p>
  * While these semantics introduce some complexity, it gives the driver the ability
  * to handle infinite result streams (like subscribing to events), significantly lowers
@@ -78,7 +78,7 @@
  *
  * @see AsyncSession
  * @see AsyncTransaction
- * @since 2.0
+ * @since 4.0
  */
 public interface AsyncQueryRunner
 {
@@ -102,7 +102,7 @@ public interface AsyncQueryRunner
      * {@code
      *
      * CompletionStage<ResultCursor> cursorStage = session.runAsync(
-     *             "MATCH (n) WHERE n.name = {myNameParam} RETURN (n)",
+     *             "MATCH (n) WHERE n.name = $myNameParam RETURN (n)",
      *             Values.parameters("myNameParam", "Bob"));
      * }
      * </pre>
@@ -136,7 +136,7 @@ public interface AsyncQueryRunner
      * parameters.put("myNameParam", "Bob");
      *
      * CompletionStage<ResultCursor> cursorStage = session.runAsync(
-     *             "MATCH (n) WHERE n.name = {myNameParam} RETURN (n)",
+     *             "MATCH (n) WHERE n.name = $myNameParam RETURN (n)",
      *             parameters);
      * }
      * </pre>
@@ -191,7 +191,7 @@ public interface AsyncQueryRunner
      * <h2>Example</h2>
      * <pre>
      * {@code
-     * Query query = new Query( "MATCH (n) WHERE n.name=$myNameParam RETURN n.age" );
+     * Query query = new Query( "MATCH (n) WHERE n.name = $myNameParam RETURN n.age" );
      * CompletionStage<ResultCursor> cursorStage = session.runAsync(query);
      * }
      * </pre>

driver/src/main/java/org/neo4j/driver/async/AsyncSession.java

@@ -34,7 +34,7 @@
 /**
  * Provides a context of work for database interactions.
  * <p>
- * A <em>AsyncSession</em> hosts a series of {@linkplain AsyncTransaction transactions}
+ * An <em>AsyncSession</em> hosts a series of {@linkplain AsyncTransaction transactions}
  * carried out against a database. Within the database, all queries are
  * carried out within a transaction. Within application code, however, it is
  * not always necessary to explicitly {@link #beginTransactionAsync() begin a
@@ -67,7 +67,7 @@
  * Similarly, multiple sessions should be used when working with concurrency;
  * session implementations are not thread safe.
  *
- * @since 2.0
+ * @since 4.0
  */
 public interface AsyncSession extends AsyncQueryRunner
 {
@@ -221,7 +221,7 @@ public interface AsyncSession extends AsyncQueryRunner
      * @return new {@link CompletionStage} that gets completed with a result cursor when query execution is successful.
      * Stage can be completed exceptionally when error happens, e.g. connection can't be acquired from the pool.
      */
-    CompletionStage<ResultCursor> runAsync(String query, TransactionConfig config );
+    CompletionStage<ResultCursor> runAsync( String query, TransactionConfig config );
 
     /**
      * Run a query asynchronously in an auto-commit transaction with the specified {@link TransactionConfig configuration} and return a
@@ -250,7 +250,7 @@ public interface AsyncSession extends AsyncQueryRunner
      * parameters.put("myNameParam", "Bob");
      *
      * CompletionStage<ResultCursor> cursorStage = session.runAsync(
-     *             "MATCH (n) WHERE n.name = {myNameParam} RETURN (n)",
+     *             "MATCH (n) WHERE n.name = $myNameParam RETURN (n)",
      *             parameters,
      *             config);
      * }
@@ -264,7 +264,7 @@ public interface AsyncSession extends AsyncQueryRunner
      * @return new {@link CompletionStage} that gets completed with a result cursor when query execution is successful.
      * Stage can be completed exceptionally when error happens, e.g. connection can't be acquired from the pool.
      */
-    CompletionStage<ResultCursor> runAsync(String query, Map<String,Object> parameters, TransactionConfig config );
+    CompletionStage<ResultCursor> runAsync( String query, Map<String,Object> parameters, TransactionConfig config );
 
     /**
      * Run a query asynchronously in an auto-commit transaction with the specified {@link TransactionConfig configuration} and return a
@@ -280,7 +280,7 @@ public interface AsyncSession extends AsyncQueryRunner
      *                 .withMetadata(metadata)
      *                 .build();
      *
-     * Query query = new Query( "MATCH (n) WHERE n.name=$myNameParam RETURN n.age" );
+     * Query query = new Query( "MATCH (n) WHERE n.name = $myNameParam RETURN n.age" );
      * CompletionStage<ResultCursor> cursorStage = session.runAsync(query, config);
      * }
      * </pre>
@@ -292,7 +292,7 @@ public interface AsyncSession extends AsyncQueryRunner
      * @return new {@link CompletionStage} that gets completed with a result cursor when query execution is successful.
      * Stage can be completed exceptionally when error happens, e.g. connection can't be acquired from the pool.
      */
-    CompletionStage<ResultCursor> runAsync(Query query, TransactionConfig config );
+    CompletionStage<ResultCursor> runAsync( Query query, TransactionConfig config );
 
     /**
      * Return the bookmark received following the last completed

driver/src/main/java/org/neo4j/driver/async/AsyncTransaction.java

@@ -39,7 +39,7 @@
  * {@code
  * session.beginTransactionAsync()
  *        .thenCompose(tx ->
- *               tx.runAsync("CREATE (a:Person {name: {x}})", parameters("x", "Alice"))
+ *               tx.runAsync("CREATE (a:Person {name: $name})", parameters("name", "Alice"))
  *                 .exceptionally(e -> {
  *                    e.printStackTrace();
  *                    return null;
@@ -53,7 +53,7 @@
  *
  * @see Session#run
  * @see QueryRunner
- * @since 2.0
+ * @since 4.0
  */
 public interface AsyncTransaction extends AsyncQueryRunner
 {

driver/src/main/java/org/neo4j/driver/async/AsyncTransactionWork.java

@@ -24,7 +24,7 @@
  * {@link AsyncSession#writeTransactionAsync(AsyncTransactionWork)} (AsyncTransactionWork)} methods.
  *
  * @param <T> the return type of this work.
- * @since 2.0
+ * @since 4.0
  */
 public interface AsyncTransactionWork<T>
 {

driver/src/main/java/org/neo4j/driver/exceptions/FatalDiscoveryException.java

@@ -21,7 +21,7 @@
 /**
  * This error indicate a fatal problem to obtain routing tables such as the routing table for a specified database does not exist.
  * This exception should not be retried.
- * @since 2.0
+ * @since 4.0
  */
 public class FatalDiscoveryException extends ClientException
 {

driver/src/main/java/org/neo4j/driver/exceptions/value/Unsizable.java

@@ -19,7 +19,7 @@
 package org.neo4j.driver.exceptions.value;
 
 /**
- * A <em>Unsizable</em> exception indicates that the value does not have a size.
+ * An <em>Unsizable</em> exception indicates that the value does not have a size.
  * @since 1.0
  */
 public class Unsizable extends ValueException

driver/src/main/java/org/neo4j/driver/reactive/RxQueryRunner.java

@@ -29,7 +29,7 @@
  * Common interface for components that can execute Neo4j queries using Reactive API.
  * @see RxSession
  * @see RxTransaction
- * @since 2.0
+ * @since 4.0
  */
 public interface RxQueryRunner
 {