From a1a217a34cf9f66fa852d0b3c007a9e7c5fa5100 Mon Sep 17 00:00:00 2001
From: Mark Paluch <mpaluch@pivotal.io>
Date: Fri, 6 Dec 2019 11:07:20 +0100
Subject: [PATCH] #205 - Polishing.

Tweak javadoc and reference documentation.
---
 pom.xml                                         | 17 +++++++++++++++++
 src/main/asciidoc/index.adoc                    |  6 ++++++
 src/main/asciidoc/new-features.adoc             |  5 ++++-
 .../asciidoc/reference/r2dbc-transactions.adoc  |  1 -
 .../R2dbcTransactionManager.java                |  2 +-
 .../SingleConnectionConnectionFactory.java      |  7 ++++---
 .../connectionfactory/init/ScriptUtils.java     |  8 ++++----
 .../data/r2dbc/convert/ColumnMapRowMapper.java  |  2 +-
 .../data/r2dbc/core/NamedParameterExpander.java |  2 --
 .../data/r2dbc/core/PreparedOperation.java      |  3 +--
 .../data/r2dbc/dialect/BindMarkersFactory.java  |  8 ++++----
 .../repository/query/AbstractR2dbcQuery.java    |  2 +-
 12 files changed, 43 insertions(+), 20 deletions(-)

diff --git a/pom.xml b/pom.xml
index 561edc94..785a1ea5 100644
--- a/pom.xml
+++ b/pom.xml
@@ -280,6 +280,7 @@
 	</dependencies>
 
 	<build>
+
 		<plugins>
 
 			<!--
@@ -303,6 +304,22 @@
 				</executions>
 			</plugin>
 
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-javadoc-plugin</artifactId>
+				<configuration>
+					<links>
+						<link>https://docs.spring.io/spring/docs/${spring}/javadoc-api/
+						</link>
+						<link>
+							https://docs.spring.io/spring-data/commons/docs/current/api/
+						</link>
+						<link>https://docs.oracle.com/javase/8/docs/api/</link>
+						<link>https://r2dbc.io/spec/0.8.0.RELEASE/api/</link>
+					</links>
+				</configuration>
+			</plugin>
+
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-surefire-plugin</artifactId>
diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc
index 0970638d..34e534a5 100644
--- a/src/main/asciidoc/index.adoc
+++ b/src/main/asciidoc/index.adoc
@@ -41,3 +41,9 @@ include::reference/r2dbc-initialization.adoc[leveloffset=+1]
 include::reference/mapping.adoc[leveloffset=+1]
 
 include::reference/kotlin.adoc[leveloffset=+1]
+
+[[appendix]]
+= Appendix
+
+:numbered!:
+include::{spring-data-commons-docs}/repository-query-return-types-reference.adoc[leveloffset=+1]
diff --git a/src/main/asciidoc/new-features.adoc b/src/main/asciidoc/new-features.adoc
index da79a551..adb450d1 100644
--- a/src/main/asciidoc/new-features.adoc
+++ b/src/main/asciidoc/new-features.adoc
@@ -4,7 +4,10 @@
 [[new-features.1-0-0-RELEASE]]
 == What's New in Spring Data R2DBC 1.0.0 RELEASE
 
-* `@Modifying` annotation for query methods to consume affected row count
+* Upgrade to R2DBC 0.8.0.RELEASE.
+* `@Modifying` annotation for query methods to consume affected row count.
+* Repository `save(…)` with an associated Id terminates with `TransientDataAccessException` if the row does not exist in the database.
+* Added `SingleConnectionConnectionFactory` for testing using connection singletons.
 
 [[new-features.1-0-0-RC1]]
 == What's New in Spring Data R2DBC 1.0.0 RC1
diff --git a/src/main/asciidoc/reference/r2dbc-transactions.adoc b/src/main/asciidoc/reference/r2dbc-transactions.adoc
index 4db73f90..30774b76 100644
--- a/src/main/asciidoc/reference/r2dbc-transactions.adoc
+++ b/src/main/asciidoc/reference/r2dbc-transactions.adoc
@@ -6,7 +6,6 @@ Relational databases typically associate a transaction with a single transport c
 Consequently, using different connections results in using different transactions.
 Spring Data R2DBC includes transaction-awareness in `DatabaseClient` that lets you group multiple statements within the same transaction by using {spring-framework-ref}/data-access.html#transaction[Spring's Transaction Management].
 Spring Data R2DBC provides an implementation for `ReactiveTransactionManager` with `R2dbcTransactionManager`.
-See <<r2dbc.connections.R2dbcTransactionManager>> for further details.
 
 The following example shows how to programmatically manage a transaction
 
diff --git a/src/main/java/org/springframework/data/r2dbc/connectionfactory/R2dbcTransactionManager.java b/src/main/java/org/springframework/data/r2dbc/connectionfactory/R2dbcTransactionManager.java
index 7a48a08d..91bb585d 100644
--- a/src/main/java/org/springframework/data/r2dbc/connectionfactory/R2dbcTransactionManager.java
+++ b/src/main/java/org/springframework/data/r2dbc/connectionfactory/R2dbcTransactionManager.java
@@ -422,7 +422,7 @@ public class R2dbcTransactionManager extends AbstractReactiveTransactionManager
 	 *
 	 * @param con the transactional R2DBC Connection
 	 * @param definition the current transaction definition
-	 * @param definition the transaction object
+	 * @param transaction the transaction object
 	 * @see #setEnforceReadOnly
 	 */
 	protected Mono<Void> prepareTransactionalConnection(Connection con, TransactionDefinition definition,
diff --git a/src/main/java/org/springframework/data/r2dbc/connectionfactory/SingleConnectionConnectionFactory.java b/src/main/java/org/springframework/data/r2dbc/connectionfactory/SingleConnectionConnectionFactory.java
index 5e94450a..612aee7b 100644
--- a/src/main/java/org/springframework/data/r2dbc/connectionfactory/SingleConnectionConnectionFactory.java
+++ b/src/main/java/org/springframework/data/r2dbc/connectionfactory/SingleConnectionConnectionFactory.java
@@ -42,8 +42,9 @@ import org.springframework.util.Assert;
  * will never call close on the Connection handle if it is SmartDataSource-aware (e.g. uses
  * {@link ConnectionFactoryUtils#releaseConnection(io.r2dbc.spi.Connection, ConnectionFactory)}).
  * <p>
- * If client code will call {@link #close()} in the assumption of a pooled Connection, like when using persistence
- * tools, set "suppressClose" to "true". This will return a close-suppressing proxy instead of the physical Connection.
+ * If client code will call {@link Connection#close()} in the assumption of a pooled Connection, like when using
+ * persistence tools, set "suppressClose" to "true". This will return a close-suppressing proxy instead of the physical
+ * Connection.
  * <p>
  * This is primarily intended for testing. For example, it enables easy testing outside an application server, for code
  * that expects to work on a {@link ConnectionFactory}.
@@ -99,7 +100,7 @@ public class SingleConnectionConnectionFactory extends DelegatingConnectionFacto
 	 * @param target underlying target {@link Connection}.
 	 * @param metadata {@link ConnectionFactory} metadata to be associated with this {@link ConnectionFactory}.
 	 * @param suppressClose if the {@link Connection} should be wrapped with a {@link Connection} that suppresses
-	 *          {@code close()} calls (to allow for normal {@link #close()} usage in applications that expect a pooled
+	 *          {@code close()} calls (to allow for normal {@code close()} usage in applications that expect a pooled
 	 *          {@link Connection} but do not know our {@link SmartConnectionFactory} interface).
 	 */
 	public SingleConnectionConnectionFactory(Connection target, ConnectionFactoryMetadata metadata,
diff --git a/src/main/java/org/springframework/data/r2dbc/connectionfactory/init/ScriptUtils.java b/src/main/java/org/springframework/data/r2dbc/connectionfactory/init/ScriptUtils.java
index 2b7034e8..1633d324 100644
--- a/src/main/java/org/springframework/data/r2dbc/connectionfactory/init/ScriptUtils.java
+++ b/src/main/java/org/springframework/data/r2dbc/connectionfactory/init/ScriptUtils.java
@@ -67,10 +67,10 @@ public abstract class ScriptUtils {
 	 * End of file (EOF) SQL statement separator: {@code "^^^ END OF SCRIPT ^^^"}.
 	 * <p/>
 	 * This value may be supplied as the {@code separator} to
-	 * {@link #executeSqlScript(Connection, EncodedResource, boolean, boolean, String, String, String, String)} to denote
-	 * that an SQL script contains a single statement (potentially spanning multiple lines) with no explicit statement
-	 * separator. Note that such a script should not actually contain this value; it is merely a <em>virtual</em>
-	 * statement separator.
+	 * {@link #executeSqlScript(Connection, EncodedResource, DataBufferFactory, boolean, boolean, String, String, String, String)}
+	 * to denote that an SQL script contains a single statement (potentially spanning multiple lines) with no explicit
+	 * statement separator. Note that such a script should not actually contain this value; it is merely a
+	 * <em>virtual</em> statement separator.
 	 */
 	public static final String EOF_STATEMENT_SEPARATOR = "^^^ END OF SCRIPT ^^^";
 
diff --git a/src/main/java/org/springframework/data/r2dbc/convert/ColumnMapRowMapper.java b/src/main/java/org/springframework/data/r2dbc/convert/ColumnMapRowMapper.java
index 4ce484bb..88c215f3 100644
--- a/src/main/java/org/springframework/data/r2dbc/convert/ColumnMapRowMapper.java
+++ b/src/main/java/org/springframework/data/r2dbc/convert/ColumnMapRowMapper.java
@@ -89,7 +89,7 @@ public class ColumnMapRowMapper implements BiFunction<Row, RowMetadata, Map<Stri
 	/**
 	 * Retrieve a R2DBC object value for the specified column.
 	 * <p>
-	 * The default implementation uses the {@link Row#get(Object)} method.
+	 * The default implementation uses the {@link Row#get(int)} method.
 	 *
 	 * @param row is the {@link Row} holding the data.
 	 * @param index is the column index.
diff --git a/src/main/java/org/springframework/data/r2dbc/core/NamedParameterExpander.java b/src/main/java/org/springframework/data/r2dbc/core/NamedParameterExpander.java
index 425babc9..6c720ff8 100644
--- a/src/main/java/org/springframework/data/r2dbc/core/NamedParameterExpander.java
+++ b/src/main/java/org/springframework/data/r2dbc/core/NamedParameterExpander.java
@@ -61,8 +61,6 @@ public class NamedParameterExpander {
 
 	/**
 	 * Create a new enabled instance of {@link NamedParameterExpander}.
-	 *
-	 * @return a new enabled instance of {@link NamedParameterExpander}.
 	 */
 	public NamedParameterExpander() {}
 
diff --git a/src/main/java/org/springframework/data/r2dbc/core/PreparedOperation.java b/src/main/java/org/springframework/data/r2dbc/core/PreparedOperation.java
index 1d21a1de..416e2f72 100644
--- a/src/main/java/org/springframework/data/r2dbc/core/PreparedOperation.java
+++ b/src/main/java/org/springframework/data/r2dbc/core/PreparedOperation.java
@@ -28,8 +28,7 @@ import org.springframework.data.r2dbc.dialect.BindTarget;
  *
  * @param <T> underlying operation source.
  * @author Mark Paluch
- * @see org.springframework.data.r2dbc.core.DatabaseClient
- * @see org.springframework.data.r2dbc.core.DatabaseClient.SqlSpec#sql(Supplier)
+ * @see org.springframework.data.r2dbc.core.DatabaseClient#execute(Supplier)
  */
 public interface PreparedOperation<T> extends QueryOperation {
 
diff --git a/src/main/java/org/springframework/data/r2dbc/dialect/BindMarkersFactory.java b/src/main/java/org/springframework/data/r2dbc/dialect/BindMarkersFactory.java
index f86c1ced..15755ccc 100644
--- a/src/main/java/org/springframework/data/r2dbc/dialect/BindMarkersFactory.java
+++ b/src/main/java/org/springframework/data/r2dbc/dialect/BindMarkersFactory.java
@@ -97,8 +97,8 @@ public interface BindMarkersFactory {
 	 *          actual identifier.
 	 * @param maxLength maximal length of parameter names when using name hints.
 	 * @return a {@link BindMarkersFactory} using {@code prefix} and {@code beginWith}.
-	 * @see io.r2dbc.spi.Statement#bindNull(Object, Class)
-	 * @see io.r2dbc.spi.Statement#bind(Object, Object)
+	 * @see io.r2dbc.spi.Statement#bindNull(String, Class)
+	 * @see io.r2dbc.spi.Statement#bind(String, Object)
 	 */
 	static BindMarkersFactory named(String prefix, String namePrefix, int maxLength) {
 		return named(prefix, namePrefix, maxLength, Function.identity());
@@ -117,8 +117,8 @@ public interface BindMarkersFactory {
 	 * @param hintFilterFunction filter {@link Function} to consider database-specific limitations in bind marker/variable
 	 *          names such as ASCII chars only.
 	 * @return a {@link BindMarkersFactory} using {@code prefix} and {@code beginWith}.
-	 * @see io.r2dbc.spi.Statement#bindNull(Object, Class)
-	 * @see io.r2dbc.spi.Statement#bind(Object, Object)
+	 * @see io.r2dbc.spi.Statement#bindNull(String, Class)
+	 * @see io.r2dbc.spi.Statement#bind(String, Object)
 	 */
 	static BindMarkersFactory named(String prefix, String namePrefix, int maxLength,
 			Function<String, String> hintFilterFunction) {
diff --git a/src/main/java/org/springframework/data/r2dbc/repository/query/AbstractR2dbcQuery.java b/src/main/java/org/springframework/data/r2dbc/repository/query/AbstractR2dbcQuery.java
index 397d7601..079d957d 100644
--- a/src/main/java/org/springframework/data/r2dbc/repository/query/AbstractR2dbcQuery.java
+++ b/src/main/java/org/springframework/data/r2dbc/repository/query/AbstractR2dbcQuery.java
@@ -165,7 +165,7 @@ public abstract class AbstractR2dbcQuery implements RepositoryQuery {
 	 * Creates a {@link BindableQuery} instance using the given {@link ParameterAccessor}
 	 *
 	 * @param accessor must not be {@literal null}.
-	 * @return
+	 * @return the {@link BindableQuery}.
 	 */
 	protected abstract BindableQuery createQuery(RelationalParameterAccessor accessor);
 }