Update documentation.

Add section on reserved method names within repository interfaces.

Closes #3173
Original pull request: #3174

Author: christophstrobl

src/main/antora/modules/ROOT/pages/repositories/core-concepts.adoc

@@ -37,6 +37,11 @@ public interface CrudRepository<T, ID> extends Repository<T, ID> {
 The methods declared in this interface are commonly referred to as CRUD methods.
 `ListCrudRepository` offers equivalent methods, but they return `List` where the `CrudRepository` methods return an `Iterable`.
 
+[IMPORTANT]
+====
+The repository interface implies a few reserved methods like `findById(ID identifier)` that always target the domain types identifier property regardless of its property name. Read more about this in "`xref:repositories/query-methods-details.adoc#repositories.query-methods.reserved-methods[Defining Query Methods]`".
+====
+
 NOTE: We also provide persistence technology-specific abstractions, such as `JpaRepository` or `MongoRepository`.
 Those interfaces extend `CrudRepository` and expose the capabilities of the underlying persistence technology in addition to the rather generic persistence technology-agnostic interfaces such as `CrudRepository`.
 

src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc

@@ -21,6 +21,20 @@ Consult the store-specific documentation for the exact list of supported keyword
 |`…Distinct…`| Use a distinct query to return only unique results. Consult the store-specific documentation whether that feature is supported. This keyword can occur in any place of the subject between `find` (and the other keywords) and `by`.
 |===============
 
+[[appendix.query.method.reserved]]
+== Reserved methods
+
+The following table lists reserved methods that use predefined functionality which is directly invoked on the backing (store specific) implementation of the repository proxy. See also "`xref:repositories/query-methods-details.adoc#repositories.query-methods.reserved-methods[Defining Query Methods]`".
+
+.Reserved methods
+|===============
+|`deleteAllById(Iterable<ID> identifiers)`
+|`deleteById(ID identifier)`
+|`existsById(ID identifier)`
+|`findAllById(Iterable<ID> identifiers)`
+|`findById(ID identifier)`
+|===============
+
 [[appendix.query.method.predicate]]
 == Supported query method predicate keywords and modifiers
 

src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc

@@ -86,6 +86,37 @@ Whether ignoring cases is supported may vary by store, so consult the relevant s
 - You can apply static ordering by appending an `OrderBy` clause to the query method that references a property and by providing a sorting direction (`Asc` or `Desc`).
 To create a query method that supports dynamic sorting, see "`xref:repositories/query-methods-details.adoc#repositories.special-parameters[Paging, Iterating Large Results, Sorting & Limiting]`".
 
+[[repositories.query-methods.reserved-methods]]
+== Reserved Methods
+
+While repository methods typically bind to properties by name, there are a few exceptions to this rule when it comes to certain method names targeting the _identifier_ property. Those _reserved methods_ like `CrudRepository#findById` or just `findById` are targeting the _identifier_ property independent of the actual property name used in the declared method. +
+Consider the following domain type holding a property `pk` marked as the identifier via `@Id` and a property called `id`. In this case you need to pay close attention to the naming of your lookup methods as they may collide with predefined signatures.
+
+====
+[source,java]
+----
+public class User {
+  @Id
+  Long pk; <1>
+  Long id; <2>
+  // ...
+}
+
+public interface UserRepository extends Repository<User, Long> {
+  Optional<User> findById(Long id); <3>
+  Optional<User> findByPk(Long pk); <4>
+  Optional<User> findUserById(Long id); <5>
+}
+----
+<1> The identifier property / primary key.
+<2> A property called id, but not the identifying one.
+<3> Targets the `User#pk` property (the one marked with `@Id` which is considered to be the identifier) instead of `User#id` as the property name would suggest because it is one of the _reserved methods_.
+<4> Targets the `User#pk` property by name.
+<5> Targets the `User#id` property by using the descriptive token between `find` and `by` to avoid collisions with _reserved methods_.
+====
+
+This special behaviour not only targets lookup methods but also applies to the `exits` and `delete` ones. Please refer to the "`xref:repositories/query-keywords-reference.adoc#appendix.query.method.reserved[Repository query keywords]`" for the list of methods.
+
 [[repositories.query-methods.query-property-expressions]]
 == Property Expressions