FMWK-263 Update documentation

README.adoc

@@ -141,7 +141,7 @@ In order to configure Spring Data Aerospike you will need to create a configurat
 `AbstractAerospikeDataConfiguration`, defines the relevant Spring Data Repositories via `@EnableAerospikeRepositories`
 annotation and overrides `getHosts()` and `nameSpace()` methods with the required connection details.
 
-You can optionally override other methods of `AbstractAerospikeDataConfiguration` to customize your configuration.
+NOTE: You can optionally override xref:#configure-data-settings[`configureDataSettings`] method of `AbstractAerospikeDataConfiguration` to further customize your configuration.
 
 Here is a simple example of a configuration class that sets up a connection to a local Aerospike instance:
 
@@ -213,7 +213,7 @@ Features supported by `AerospikeOperations`:
 
 * Basic support for mapping POJOs to and from Aerospike bins
 * Convenience CRUD (Create, Read, Update and Delete) methods for interacting with Aerospike
-* Rich Query API
+* Rich query API
 * Access to the native Aerospike Java Client (reactive and non-reactive)
 * Translating exceptions into Spring's
 https://docs.spring.io/spring/docs/current/spring-framework-reference/html/dao.html#dao-exceptions[technology-agnostic

src/main/asciidoc/index.adoc

@@ -1,6 +1,6 @@
 = Spring Data Aerospike - Documentation
 :doctype: book
-:revnumber: 4.5.0
+:revnumber: 4.6.0
 :revdate: {localdate}
 :toc:
 :toc-placement!:
@@ -24,9 +24,8 @@ include::preface.adoc[]
 
 :leveloffset: +1
 
-include::reference/introduction.adoc[]
-include::reference/aerospike.adoc[]
-include::reference/getting-started.adoc[]
+include::reference/functionality.adoc[]
+include::reference/installation-and-usage.adoc[]
 include::spring-data-commons-docs/repositories.adoc[]
 include::reference/aerospike-repositories.adoc[]
 include::reference/aerospike-reactive-repositories.adoc[]
@@ -40,6 +39,7 @@ include::reference/template.adoc[]
 include::reference/secondary-indexes.adoc[]
 include::reference/indexed-annotation.adoc[]
 include::reference/caching.adoc[]
+include::reference/configure-data-settings.adoc[]
 include::spring-data-commons-docs/dependencies.adoc[]
 include::spring-data-commons-docs/auditing.adoc[]
 

src/main/asciidoc/preface.adoc

@@ -26,9 +26,9 @@ The jumping off ground for learning about Aerospike is https://www.aerospike.com
 [[requirements]]
 == Requirements
 
-Spring Data Aerospike binaries require JDK level 17.0 and above, and https://spring.io/docs[Spring Framework] 5.3.x and above.
+Spring Data Aerospike binaries require JDK level 17.0 and above.
 
-In terms of server, https://www.aerospike.com/download/server/[Aerospike] version at least 5.2
+In terms of server, it is required to use  at least https://www.aerospike.com/download/server/[Aerospike server] version 5.2 (recommended to use the latest version when possible).
 
 == Additional Help Resources
 

src/main/asciidoc/reference/aerospike-object-mapping.adoc

@@ -1,4 +1,4 @@
-[[mapping-chapter]]
+[[aerospike.object-mapping]]
 = Aerospike Object Mapping
 
 Rich mapping support is provided by the `AerospikeMappingConverter`. `AerospikeMappingConverter` has a rich metadata model that provides a full feature set of functionality to map domain objects to Aerospike clusters and objects.The mapping metadata model is populated using annotations on your domain objects. However, the infrastructure is not limited to using annotations as the only source of metadata information. The `AerospikeMappingConverter` also allows you to map objects without providing any additional metadata, by following a set of conventions.
@@ -49,8 +49,8 @@ The following outlines what field will be mapped to the '_id' document field:
 
 The following outlines what type of conversion, if any, will be done on the property mapped to the _id document field.
 
-* If a field named 'id' is declared as a String or BigInteger in the Java class it will be converted to and stored as a string. 
-* If no field named 'id' is present in the Java class then an implicit '_id' file will be generated by the driver but not mapped to a property or field of the Java class.
+* By default, the type of the field annotated with `@id` is turned into a `String` to be stored in Aerospike database. If the original type cannot be persisted (see xref:#configure-data-settings.keep-original-key-types[keepOriginalKeyTypes] for details), it must be convertible to `String` and will be stored in the database as such, then converted back to the original type when the object is read. This is transparent to the application but needs to be considered if using external tools like `AQL` to view the data.
+* If no field named "id" is present in the Java class then an implicit '_id' file will be generated by the driver but not mapped to a property or field of the Java class.
 
 When querying and updating `AerospikeTemplate` will use the converter to handle conversions of the `Query` and `Update` objects that correspond to the above rules for saving documents so field names and types used in your queries will be able to match what is in your domain classes.
 

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

@@ -4,12 +4,17 @@
 [[aerospike-repo-intro]]
 == Introduction
 
-This chapter will point out the specialties for repository support for Aerospike. This builds on the <<repositories, Core SpringData Repository Support>>, so make sure you've got a sound understanding of the basic concepts explained there.
+One of the main goals of the Spring Data is to significantly reduce the amount of boilerplate code required to implement data access layers for various persistence stores.
+
+One of the core interfaces of Spring Data is `Repository`.
+This interface acts primarily to capture the types to work with and to help user to discover interfaces that extend Repository.
+
+In other words, it allows user to have basic and complicated queries without writing the implementation. This builds on the <<repositories, Core SpringData Repository Support>>, so make sure you've got a sound understanding of this concept.
 
 [[aerospike-repo-usage]]
 == Usage
 
-To access domain entities stored in a Aerospike you can leverage our sophisticated repository support that eases implementing those quite significantly. To do so, simply create an interface for your repository:
+To access entities stored in Aerospike you can leverage repository support that eases implementing those quite significantly. To do so, simply create an interface for your repository:
 
 .Sample Person entity
 ====
@@ -30,7 +35,7 @@ public class Person {
 }
 ----
 ====
-We have a quite simple domain object here. The default serialization mechanism used in `AerospikeTemplate` (which is backing the repository support) regards properties named id as document id. Currently, we support`String` and `long` as id-types.
+We have a quite simple domain object here. The default serialization mechanism used in `AerospikeTemplate` (which is backing the repository support) regards properties named "id" as document id. Currently we support `String` and `long` as id-types.
 
 .Basic repository interface to persist Person entities
 ====
@@ -46,7 +51,7 @@ public interface PersonRepository extends AerospikeRepository<Person, String> {
 ----
 ====
 
-Right now this interface simply serves typing purposes but we will add additional methods to it later. In your Spring configuration simply add
+Right now this interface simply serves typing purposes, but we will add additional methods to it later. In your Spring configuration simply add
 
 .General Aerospike repository Spring configuration
 ====
@@ -142,8 +147,8 @@ public interface PersonRepository extends PagingAndSortingRepository<Person, Str
  }
 ----
 <1> The method shows a query for all people with the given name. The query will be derived by parsing the method name for constraints that can be concatenated with `And` and `Or`.
-<2> Applies pagination to a query. Just equip your method signature with a `Pageable` parameter and let the method return a `Page` instance and we will automatically page the query accordingly.
-<3> Shows that you can query-based partial name searches.
+<2> Applies pagination to a query. Just equip your method signature with a `Pageable` parameter and let the method return a `Page` instance, and it will automatically page the query accordingly (i.e. return the required part of results).
+<3> Uses query-based partial name search.
 ====
 [[aerospike.repositories.example]]
 
@@ -160,9 +165,6 @@ public class RepositoryExample {
 	@Autowired
 	AerospikeClient client;
 
-	/**
-	 * @param ctx
-	 */
 	public RepositoryExample(ApplicationContext ctx) {
 		aerospikeOperations = ctx.getBean(AerospikeTemplate.class);
 		repository = (PersonRepository) ctx.getBean("personRepository");
@@ -196,7 +198,7 @@ public class RepositoryExample {
 		for (Person person : result) {
 			System.out.println(person.toString());
 		}
-		System.out.println("Results for name startting with letter 'M'");
+		System.out.println("Results for name starting with letter 'M'");
 		List<Person> resultPartial = repository.findByNameStartsWith("M");
 		for (Person person : resultPartial) {
 			System.out.println(person.toString());