Increase documentation about new features at Spec and readme

README.adoc

@@ -9,7 +9,9 @@ Jakarta Data’s goal is to provide a familiar and consistent, Jakarta-based pro
 
 === Repository
 
-A repository abstraction designed to significantly reduce the boilerplate code required to implement data access layers for various types of persistent stores.
+Jakarta Data provides repository abstractions designed to streamline the development of data access layers for various persistent stores, eliminating the need for extensive boilerplate code. These repository abstractions are broadly classified into two categories:
+
+* *Built-in Repository Interfaces*: Jakarta Data offers a hierarchy of built-in repository interfaces. The root of this hierarchy is the `DataRepository` interface, which includes several specialized interfaces like `CrudRepository`, `BasicRepository`, and more. These interfaces are designed to handle common data access operations and provide an extensible foundation for your data layer.
 
 [source,java]
 ----
@@ -33,6 +35,32 @@ Car ferrari = Car.id(10L).name("Ferrari").type(CarType.SPORT);
 repository.save(ferrari);
 ----
 
+* *Custom Repository Interfaces*: Besides the built-in repository interfaces, Jakarta Data enables you to create custom repository interfaces tailored to your domain requirements. These custom interfaces serve as a bridge between your domain's semantics and the underlying database operations. With annotations like `Insert`, `Update`, `Delete`, and `Save`, you can define expressive and domain-specific repository methods that align seamlessly with your application's needs.
+
+[source,java]
+----
+@Repository
+public interface Garage {
+
+  @Insert
+  Car park(Car car);
+
+}
+----
+
+
+[source,java]
+----
+@Inject
+Garage garage;
+...
+Car ferrari = Car.id(10L).name("Ferrari").type(CarType.SPORT);
+repository.park(ferrari);
+----
+
+Whether you use built-in repository interfaces or create custom repositories, Jakarta Data empowers you to write more concise and expressive data access layers while reducing the need for boilerplate code.
+
+
 ==== Pagination
 
 Jakarta Data also supports parameters to define pagination and sorting.

spec/src/main/asciidoc/repository.asciidoc

@@ -54,7 +54,9 @@ Several vital characteristics define repositories:
 
 Repositories in Jakarta Data serve as efficient gateways for managing and interacting with persistent data, offering a simplified and consistent approach to data access and modification within Java applications.
 
-The parent interface at the root of the hierarchy of built-in interfaces is `DataRepository`. All of the built-in interfaces are extensible. A repository might extend one or more of the built-in interfaces or none of them. Method signatures that are copied from the built-in interfaces to a repository must have the same behavior as defined on the built-in interface.
+The Jakarta Data specification supports two types of repositories.
+
+The first type consists of built-in interfaces that are parent interfaces from which repositories can inherit. At the root of this hierarchy is the `DataRepository` interface. These built-in interfaces are extensible, meaning a repository can extend one or more of them or none at all. When a repository extends a built-in interface, the method signatures copied from the built-in interfaces must retain the same behavior as defined in the built-in interfaces.
 
 [ditaa]
 ....
@@ -108,10 +110,34 @@ Jakarta Data empowers developers to take control of their data access and manage
 
 2. **Repository Interfaces:** Jakarta Data encourages the creation of one or more repository interfaces, following predefined rules that include the guidelines set forth by this specification. These interfaces are the gateways to accessing and manipulating the data, offering a structured and efficient way to perform data operations.
 
+
 Subsequently, an implementation of Jakarta Data, specifically tailored to the chosen data store, assumes the responsibility of implementing each repository interface. This symbiotic relationship between developers and Jakarta Data ensures that data access and manipulation remain consistent, efficient, and aligned with best practices.
 
 Jakarta Data empowers developers to shape their data access strategies by defining entity classes and repositories, with implementations seamlessly adapting to the chosen data store. This flexibility and Jakarta Data's persistence-agnostic approach promote robust data management within Java applications.
 
+Additionally, Jakarta Data allows for custom interfaces that do not extend any built-in interfaces. These non-built-in interfaces enable developers to define their repository structures and behavior.
+
+Non-built-in interfaces play a pivotal role in Jakarta Data, offering a powerful mechanism for creating custom repository interfaces that align seamlessly with your specific domain requirements. These custom interfaces provide a means to define your domain's ubiquitous language precisely.
+
+In this context, database operations involving fundamental data changes, such as insertion, update, and removal, are realized through the strategic utilization of annotations like `Insert`, `Update`, `Delete`, and `Save`. These annotations enable the crafting of expressive and contextually meaningful repository methods, resulting in a repository that closely mirrors the semantics of your domain.
+
+For instance, consider the 'Garage' repository interface below:
+
+[source,java]
+----
+@Repository
+public interface Garage {
+
+    @Insert
+    Car park(Car car);
+
+    @Delete
+    void unpark(Car car);
+}
+----
+
+Here, the `@Insert` annotation is used for the `park` method, allowing you to design a repository interface that encapsulates the essence of your domain. This approach fosters a shared understanding and more intuitive communication within your development team, ensuring that your database operations are integral to your domain's language.
+
 === Repository interfaces
 
 A Jakarta Data repository is a Java interface annotated `@Repository`.
@@ -140,7 +166,7 @@ Repositories perform operations on entities. For repository methods that are ann
 
 Users of Jakarta Data declare a primary entity type for a repository by inheriting from a built-in repository super interface, such as `BasicRepository`, and specifying the primary entity type as the first type variable.  The primary entity type is assumed for methods that do not otherwise specify an entity type, such as `countByPriceLessThan`. Methods that require a primary entity type raise `MappingException` if a primary entity type is not provided.
 
-[NOTE]
+
 NOTE: A Jakarta Data provider might go beyond what is required by this specification and support abstract methods which do not fall into any of the above categories.
 
 Such functionality is not defined by this specification, and so programs with repositories which declare such methods are not portable between providers.
@@ -345,6 +371,7 @@ public interface ProductRepository extends CrudRepository<Product, Long> {
 }
 ----
 
+
 === Entity Classes
 
 In Jakarta Data, an entity refers to a fundamental data representation and management building block. It can be conceptually understood in several aspects: