Improve documentation about name handling.

Closes #616
Original pull request: #617.

Author: schauder

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 class `com.bigbank.SavingsAccount` maps to the `SAVINGS_ACCOUNT` table name.
+The same name mapping is applied for mapping fields to column names.
+For example a field `firstName` will be mapped to a column `FIRST_NAME`
+You can control this mapping by providing a custom `NamingStrategy`. See <<mapping.configuration>> for more details.
+Table and column names that are derived from property or class names are used in SQL statements without quotes by default.
+This behaviour can be controlled 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 will be used with database specific quotes.
+This means it is ok to use reserved SQL words like for example `order` in these names.
+This can be done 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 don't use keywords or special characters in your names.
+For databases adhering to the SQL standard with that respect this means, names will be converted to upper case.
+The quoting character used, and the way names get capitalized is controlled by the used `Dialect`.
+See <<r2dbc.drivers>> for details 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 may 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 simple type by the used `R2dbcDialect`.
 
 |Complex objects
 |Target type depends on registered `Converter`.
@@ -173,7 +190,9 @@ 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, allowing the name to 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 these names are case-sensitive. It also means you may use special characters in these names, although 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 used in a `@Query` annotation must match the names generated by the `NamingStrategy` for the respective property.
+If for a property no matching column is provided in a select, that property is not set. If that property is required by the persistence constructor, `null` is provided as a value or the default value for primitive types.
+
 The following table shows the keywords that are supported for query methods:
 
 [cols="1,2,3", options="header", subs="quotes"]