Improving the documentation.

See #908
Original pull request #983

src/main/asciidoc/jdbc-custom-conversions.adoc

@@ -1,4 +1,6 @@
 [[jdbc.custom-converters]]
+// for backward compatibility only:
+[[jdbc.entity-persistence.custom-converters]]
 == Custom Conversions
 
 Spring Data JDBC allows registration of custom converters to influence how values are mapped in the database.
@@ -55,12 +57,26 @@ class MyJdbcConfiguration extends AbstractJdbcConfiguration {
 
     // …
 
-    @Overwrite
+	@Override
-    @Bean
+    protected List<?> userConverters() {
-    public JdbcCustomConversions jdbcCustomConversions() {
+		return Arrays.asList(new BooleanToStringConverter(), new StringToBooleanConverter());
-        return new JdbcCustomConversions(Arrays.asList(new BooleanToStringConverter(), new StringToBooleanConverter()));
+	}
-    }
+
 }
 ----
 
+NOTE: In previous versions of Spring Data JDBC it was recommended to directly overwrite `AbstractJdbcConfiguration.jdbcCustomConversions()`.
+This is no longer necessary or even recommended, since that method assembles conversions intended for all databases, conversions registered by the `Dialect` used and conversions registered by the user.
+If you are migrating from an older version of Spring Data JDBC and have `AbstractJdbcConfiguration.jdbcCustomConversions()` overwritten conversions from your `Dialect` will not get registered.
+
+[[jdbc.custom-converters.jdbc-value]]
+// for backward compatibility only:
+[[jdbc.entity-persistence.custom-converters.jdbc-value]]
+=== JdbcValue
+
+Value conversion uses `JdbcValue` to enrich values propagated to JDBC operations with a `java.sql.Types` type.
+Register a custom write converter if you need to specify a JDBC-specific type instead of using type derivation.
+This converter should convert the value to `JdbcValue` which has a field for the value and for the actual `JDBCType`.
+
+
 include::{spring-data-commons-docs}/custom-conversions.adoc[leveloffset=+3]

src/main/asciidoc/jdbc.adoc

@@ -263,48 +263,7 @@ p1.bestFriend = AggregateReference.to(p2.id);
 ----
 ====
 
-[[jdbc.entity-persistence.custom-converters]]
+* Types for which you registered suitable [[jdbc.custom-converters, custom conversions]].
-=== Custom converters
-
-Custom converters can be registered, for types that are not supported by default, by inheriting your configuration from `AbstractJdbcConfiguration` and overwriting the method `jdbcCustomConversions()`.
-
-====
-[source,java]
-----
-@Configuration
-class DataJdbcConfiguration extends AbstractJdbcConfiguration {
-
-    @Override
-    public JdbcCustomConversions jdbcCustomConversions() {
-      return new JdbcCustomConversions(Collections.singletonList(TimestampTzToDateConverter.INSTANCE));
-    }
-
-    @ReadingConverter
-    enum TimestampTzToDateConverter implements Converter<TIMESTAMPTZ, Date> {
-
-        INSTANCE;
-
-        @Override
-        public Date convert(TIMESTAMPTZ source) {
-            //...
-        }
-    }
-}
-----
-====
-
-The constructor of `JdbcCustomConversions` accepts a list of `org.springframework.core.convert.converter.Converter`.
-
-Converters should be annotated with `@ReadingConverter` or `@WritingConverter` in order to control their applicability to only reading from or to writing to the database.
-
-`TIMESTAMPTZ` in the example is a database specific data type that needs conversion into something more suitable for a domain model.
-
-[[jdbc.entity-persistence.custom-converters.jdbc-value]]
-==== JdbcValue
-
-Value conversion uses `JdbcValue` to enrich values propagated to JDBC operations with a `java.sql.Types` type.
-Register a custom write converter if you need to specify a JDBC-specific type instead of using type derivation.
-This converter should convert the value to `JdbcValue` which has a field for the value and for the actual `JDBCType`.
 
 [[jdbc.entity-persistence.naming-strategy]]
 === `NamingStrategy`