#8 - Polishing.

Formatting, JavaDoc, issue comments on `@Test` annotations.
Removed some dead code.

Original pull request: #33.

Author: schauder

src/main/java/org/springframework/data/r2dbc/function/DatabaseClient.java

@@ -64,7 +64,9 @@ public interface DatabaseClient {
 	// Static, factory methods
 
 	/**
-	 * A variant of {@link #create()} that accepts a {@link io.r2dbc.spi.ConnectionFactory}
+	 * Creates a {@code DatabaseClient} that will use the provided {@link io.r2dbc.spi.ConnectionFactory}.
+	 * @param factory The {@code ConnectionFactory} to use for obtaining connections.
+	 * @return a new {@code DatabaseClient}. Guaranteed to be not {@code null}.
 	 */
 	static DatabaseClient create(ConnectionFactory factory) {
 		return new DefaultDatabaseClientBuilder().connectionFactory(factory).build();
@@ -161,7 +163,7 @@ interface GenericExecuteSpec extends BindSpec<GenericExecuteSpec> {
 		 *
 		 * @param mappingFunction must not be {@literal null}.
 		 * @param <R> result type.
-		 * @return
+		 * @return a {@link FetchSpec} for configuration what to fetch. Guaranteed to be not {@code null}.
 		 */
 		<R> FetchSpec<R> map(BiFunction<Row, RowMetadata, R> mappingFunction);
 
@@ -197,7 +199,7 @@ interface TypedExecuteSpec<T> extends BindSpec<TypedExecuteSpec<T>> {
 		 *
 		 * @param mappingFunction must not be {@literal null}.
 		 * @param <R> result type.
-		 * @return
+		 * @return a {@link FetchSpec} for configuration what to fetch. Guaranteed to be not {@code null}.
 		 */
 		<R> FetchSpec<R> map(BiFunction<Row, RowMetadata, R> mappingFunction);
 
@@ -223,15 +225,15 @@ interface SelectFromSpec {
 		 * Specify the source {@literal table} to select from.
 		 *
 		 * @param table must not be {@literal null} or empty.
-		 * @return
+		 * @return a {@link GenericSelectSpec} for further configuration of the select. Guaranteed to be not {@code null}.
 		 */
 		GenericSelectSpec from(String table);
 
 		/**
 		 * Specify the source table to select from to using the {@link Class entity class}.
 		 *
 		 * @param table must not be {@literal null}.
-		 * @return
+		 * @return a {@link TypedSelectSpec} for further configuration of the select. Guaranteed to be not {@code null}.
 		 */
 		<T> TypedSelectSpec<T> from(Class<T> table);
 	}
@@ -245,15 +247,15 @@ interface InsertIntoSpec {
 		 * Specify the target {@literal table} to insert into.
 		 *
 		 * @param table must not be {@literal null} or empty.
-		 * @return
+		 * @return a {@link GenericInsertSpec} for further configuration of the insert. Guaranteed to be not {@code null}.
 		 */
 		GenericInsertSpec<Map<String, Object>> into(String table);
 
 		/**
 		 * Specify the target table to insert to using the {@link Class entity class}.
 		 *
 		 * @param table must not be {@literal null}.
-		 * @return
+		 * @return a {@link TypedInsertSpec} for further configuration of the insert. Guaranteed to be not {@code null}.
 		 */
 		<T> TypedInsertSpec<T> into(Class<T> table);
 	}
@@ -277,7 +279,7 @@ interface GenericSelectSpec extends SelectSpec<GenericSelectSpec> {
 		 *
 		 * @param mappingFunction must not be {@literal null}.
 		 * @param <R> result type.
-		 * @return
+		 * @return a {@link FetchSpec} for configuration what to fetch. Guaranteed to be not {@code null}.
 		 */
 		<R> FetchSpec<R> map(BiFunction<Row, RowMetadata, R> mappingFunction);
 
@@ -306,7 +308,7 @@ interface TypedSelectSpec<T> extends SelectSpec<TypedSelectSpec<T>> {
 		 *
 		 * @param mappingFunction must not be {@literal null}.
 		 * @param <R> result type.
-		 * @return
+		 * @return a {@link FetchSpec} for configuration what to fetch. Guaranteed to be not {@code null}.
 		 */
 		<R> FetchSpec<R> map(BiFunction<Row, RowMetadata, R> mappingFunction);
 
@@ -375,25 +377,25 @@ interface TypedInsertSpec<T> {
 		/**
 		 * Insert the given {@code objectToInsert}.
 		 *
-		 * @param objectToInsert
-		 * @return
+		 * @param objectToInsert the object of which the attributes will provide the values for the insert. Must not be {@code null}.
+		 * @return a {@link InsertSpec} for further configuration of the insert. Guaranteed to be not {@code null}.
 		 */
 		InsertSpec<Map<String, Object>> using(T objectToInsert);
 
 		/**
 		 * Use the given {@code tableName} as insert target.
 		 *
 		 * @param tableName must not be {@literal null} or empty.
-		 * @return
+		 * @return a {@link TypedInsertSpec} for further configuration of the insert. Guaranteed to be not {@code null}.
 		 */
 		TypedInsertSpec<T> table(String tableName);
 
 		/**
 		 * Insert the given {@link Publisher} to insert one or more objects. Inserts only a single object when calling
 		 * {@link FetchSpec#one()} or {@link FetchSpec#first()}.
 		 *
-		 * @param objectToInsert
-		 * @return
+		 * @param objectToInsert a publisher providing the objects of which the attributes will provide the values for the insert. Must not be {@code null}.
+		 * @return a {@link InsertSpec} for further configuration of the insert. Guaranteed to be not {@code null}.
 		 * @see InsertSpec#fetch()
 		 */
 		InsertSpec<Map<String, Object>> using(Publisher<T> objectToInsert);
@@ -411,7 +413,7 @@ interface InsertSpec<T> {
 		 *
 		 * @param mappingFunction must not be {@literal null}.
 		 * @param <R> result type.
-		 * @return
+		 * @return a {@link FetchSpec} for configuration what to fetch. Guaranteed to be not {@code null}.
 		 */
 		<R> FetchSpec<R> map(BiFunction<Row, RowMetadata, R> mappingFunction);
 
@@ -436,15 +438,15 @@ interface BindSpec<S extends BindSpec<S>> {
 		/**
 		 * Bind a non-{@literal null} value to a parameter identified by its {@code index}.
 		 *
-		 * @param index
-		 * @param value must not be {@literal null}.
+		 * @param index zero based index to bind the parameter to.
+		 * @param value to bind. Must not be {@literal null}.
 		 */
 		S bind(int index, Object value);
 
 		/**
 		 * Bind a {@literal null} value to a parameter identified by its {@code index}.
 		 *
-		 * @param index
+		 * @param index zero based index to bind the parameter to.
 		 * @param type must not be {@literal null}.
 		 */
 		S bindNull(int index, Class<?> type);