Improve documentation about name handling.

pom.xml

@@ -5,7 +5,7 @@
 
 	<groupId>org.springframework.data</groupId>
 	<artifactId>spring-data-r2dbc</artifactId>
-	<version>1.4.0-SNAPSHOT</version>
+	<version>1.4.0-616-document-naming-SNAPSHOT</version>
 
 	<name>Spring Data R2DBC</name>
 	<description>Spring Data module for R2DBC</description>

src/main/asciidoc/reference/mapping.adoc

@@ -17,7 +17,12 @@ include::../{spring-data-commons-docs}/object-mapping.adoc[leveloffset=+1]
 The conventions are:
 
 * The short Java class name is mapped to the table name in the following manner.
-The class `com.bigbank.SavingsAccount` maps to the `savings_account` table name.
+The `com.bigbank.SavingsAccount` class maps to the `SAVINGS_ACCOUNT` table name.
+The same name mapping is applied for mapping fields to column names.
+For example, the `firstName` field maps to the `FIRST_NAME` column.
+You can control this mapping by providing a custom `NamingStrategy`. See <<mapping.configuration>> for more detail.
+Table and column names that are derived from property or class names are used in SQL statements without quotes by default.
+You can control this behavior by setting `R2dbcMappingContext.setForceQuote(true)`.
 
 * Nested objects are not supported.
 
@@ -39,6 +44,15 @@ By creating your own instance, you can register Spring converters to map specifi
 
 You can configure the `MappingR2dbcConverter` as well as `DatabaseClient` and `ConnectionFactory` by using  Java-based metadata. The following example uses Spring's Java-based configuration:
 
+If you set `setForceQuote` of the `R2dbcMappingContext to` true, table and column names derived from classes and properties are used with database specific quotes.
+This means that it is OK to use reserved SQL words (such as order) in these names.
+You can do so by overriding `r2dbcMappingContext(Optional<NamingStrategy>)` of `AbstractR2dbcConfiguration`.
+Spring Data converts the letter casing of such a name to that form which is also used by the configured database when no quoting is used.
+Therefore, you can use unquoted names when creating tables, as long as you do not use keywords or special characters in your names.
+For databases that adhere to the SQL standard, this means that names are converted to upper case.
+The quoting character and the way names get capitalized is controlled by the used `Dialect`.
+See <<r2dbc.drivers>> for how to configure custom dialects.
+
 .@Configuration class to configure R2DBC mapping support
 ====
 [source,java]
@@ -68,6 +82,9 @@ public class MyAppConfig extends AbstractR2dbcConfiguration {
 
 You can add additional converters to the converter by overriding the `r2dbcCustomConversions` method.
 
+You can configure a custom `NamingStrategy` by registering it as a bean.
+The `NamingStrategy` controls how the names of classes and properties get converted to the names of tables and columns.
+
 NOTE: `AbstractR2dbcConfiguration` creates a `DatabaseClient` instance and registers it with the container under the name of `databaseClient`.
 
 [[mapping.usage]]
@@ -144,7 +161,7 @@ The following table explains how property types of an entity affect mapping:
 
 |Driver-specific types
 |Passthru
-|Contributed as simple type be the used `R2dbcDialect`.
+|Contributed as a simple type by the used `R2dbcDialect`.
 
 |Complex objects
 |Target type depends on registered `Converter`.
@@ -173,7 +190,11 @@ Constructor arguments are mapped by name to the values in the retrieved row.
 Within the mapping framework it can be applied to constructor arguments.
 This lets you use a Spring Expression Language statement to transform a key’s value retrieved in the database before it is used to construct a domain object.
 In order to reference a column of a given row one has to use expressions like: `@Value("#root.myProperty")` where root refers to the root of the given `Row`.
-* `@Column`: Applied at the field level to describe the name of the column as it is represented in the row, allowing the name to be different than the field name of the class.
+* `@Column`: Applied at the field level to describe the name of the column as it is represented in the row, letting the name be different from the field name of the class.
+Names specified with a `@Column` annotation are always quoted when used in SQL statements.
+For most databases, this means that these names are case-sensitive.
+It also means that you can use special characters in these names.
+However, this is not recommended, since it may cause problems with other tools.
 * `@Version`: Applied at field level is used for optimistic locking and checked for modification on save operations.
 The value is `null` (`zero` for primitive types) is considered as marker for entities to be new.
 The initially stored value is `zero` (`one` for primitive types).

src/main/asciidoc/reference/r2dbc-core.adoc

@@ -183,7 +183,7 @@ This approach lets you use the standard `io.r2dbc.spi.ConnectionFactory` instanc
 Spring Data R2DBC supports drivers through R2DBC's pluggable SPI mechanism.
 You can use any driver that implements the R2DBC spec with Spring Data R2DBC.
 Since Spring Data R2DBC reacts to specific features of each database, it requires a `Dialect` implementation otherwise your application won't start up.
-Spring Data R2DBC ships with dialect impelemtations for the following drivers:
+Spring Data R2DBC ships with dialect implementations for the following drivers:
 
 * https://github.com/r2dbc/r2dbc-h2[H2] (`io.r2dbc:r2dbc-h2`)
 * https://github.com/mariadb-corporation/mariadb-connector-r2dbc[MariaDB] (`org.mariadb:r2dbc-mariadb`)

src/main/asciidoc/reference/r2dbc-repositories.adoc

@@ -118,6 +118,9 @@ interface ReactivePersonRepository extends ReactiveSortingRepository<Person, Lon
 The annotated query uses native bind markers, which are Postgres bind markers in this example.
 ====
 
+Note that the columns of a select statement used in a `@Query` annotation must match the names generated by the `NamingStrategy` for the respective property.
+If a select statement does not include a matching column, that property is not set. If that property is required by the persistence constructor, either null or (for primitive types) the default value is provided.
+
 The following table shows the keywords that are supported for query methods:
 
 [cols="1,2,3", options="header", subs="quotes"]