DATAMONGO-1584 - Polishing.

Original Pull Request: #407

Author: christophstrobl

src/main/asciidoc/kotlin-coroutines.adoc

@@ -1,8 +1,8 @@
 [[kotlin.coroutines]]
 = Coroutines
 
-Kotlin https://kotlinlang.org/docs/reference/coroutines-overview.html[Coroutines] are Kotlin lightweight threads allowing to write non-blocking code imperatively.
-On language side, suspending functions provides an abstraction for asynchronous operations while on library side https://github.com/Kotlin/kotlinx.coroutines[kotlinx.coroutines] provides functions like https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/async.html[`async { }`] and types like https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[`Flow`].
+Kotlin https://kotlinlang.org/docs/reference/coroutines-overview.html[Coroutines] are lightweight threads allowing to write non-blocking code imperatively.
+On language side, `suspend` functions provides an abstraction for asynchronous operations while on library side https://github.com/Kotlin/kotlinx.coroutines[kotlinx.coroutines] provides functions like https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/async.html[`async { }`] and types like https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[`Flow`].
 
 Spring Data modules provide support for Coroutines on the following scope:
 
@@ -29,7 +29,7 @@ Coroutines support is enabled when `kotlinx-coroutines-core` and `kotlinx-corout
 ----
 ====
 
-Version `1.3.0` and above are supported.
+NOTE: Supported versions `1.3.0` and above.
 
 [[kotlin.coroutines.reactive]]
 == How Reactive translates to Coroutines?

src/main/asciidoc/kotlin-extensions.adoc

@@ -3,8 +3,11 @@
 
 Kotlin https://kotlinlang.org/docs/reference/extensions.html[extensions] provide the ability to extend existing classes with additional functionality. Spring Data Kotlin APIs use these extensions to add new Kotlin-specific conveniences to existing Spring APIs.
 
-NOTE: Keep in mind that Kotlin extensions need to be imported to be used.
+[NOTE]
+====
+Keep in mind that Kotlin extensions need to be imported to be used.
 Similar to static imports, an IDE should automatically suggest the import in most cases.
+====
 
 For example, https://kotlinlang.org/docs/reference/inline-functions.html#reified-type-parameters[Kotlin reified type parameters] provide a workaround for JVM https://docs.oracle.com/javase/tutorial/java/generics/erasure.html[generics type erasure], and Spring Data provides some extensions to take advantage of this feature.
 This allows for a better Kotlin API.

src/main/asciidoc/kotlin.adoc

@@ -3,37 +3,40 @@
 
 https://kotlinlang.org[Kotlin] is a statically typed language that targets the JVM (and other platforms) which allows writing concise and elegant code while providing excellent https://kotlinlang.org/docs/reference/java-interop.html[interoperability] with existing libraries written in Java.
 
-Spring Data provides first-class support for Kotlin and lets developers write Kotlin applications almost as if Spring Data was a Kotlin-native framework.
+Spring Data provides first-class support for Kotlin and lets developers write Kotlin applications almost as if Spring Data was a Kotlin native framework.
 
 The easiest way to build a Spring application with Kotlin is to leverage Spring Boot and its https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-kotlin.html[dedicated Kotlin support].
-https://spring.io/guides/tutorials/spring-boot-kotlin/[This comprehensive tutorial] will teach you how to build Spring Boot applications with Kotlin using https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io].
+This comprehensive https://spring.io/guides/tutorials/spring-boot-kotlin/[tutorial] will teach you how to build Spring Boot applications with Kotlin using https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io].
 
 [[kotlin.requirements]]
 == Requirements
 
 Spring Data supports Kotlin 1.3 and requires https://bintray.com/bintray/jcenter/org.jetbrains.kotlin%3Akotlin-stdlib[`kotlin-stdlib`] (or one of its variants, such as https://bintray.com/bintray/jcenter/org.jetbrains.kotlin%3Akotlin-stdlib-jdk8[`kotlin-stdlib-jdk8`]) and https://bintray.com/bintray/jcenter/org.jetbrains.kotlin%3Akotlin-reflect[`kotlin-reflect`] to be present on the classpath.
-They are provided by default if you bootstrap a Kotlin project on https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io].
+Those are provided by default if you bootstrap a Kotlin project via https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io].
 
 [[kotlin.null-safety]]
-== Null-safety
+== Null Safety
 
-One of Kotlin's key features is https://kotlinlang.org/docs/reference/null-safety.html[null-safety], which cleanly deals with `null` values at compile time rather than bumping into the famous `NullPointerException` at runtime.
-This makes applications safer through nullability declarations and expressing "`value or no value`" semantics without paying the cost of wrappers, such as `Optional`.
-(Kotlin allows using functional constructs with nullable values. See this https://www.baeldung.com/kotlin-null-safety[comprehensive guide to Kotlin null-safety].)
+One of Kotlin's key features is https://kotlinlang.org/docs/reference/null-safety.html[null safety], which cleanly deals with `null` values at compile time.
+This makes applications safer through nullability declarations and the expression of "`value or no value`" semantics without paying the cost of wrappers, such as `Optional`.
+(Kotlin allows using functional constructs with nullable values. See this https://www.baeldung.com/kotlin-null-safety[comprehensive guide to Kotlin null safety].)
 
-Although Java does not let you express null-safety in its type-system, Spring Data API is annotated with JSR-305 tooling-friendly annotations declared in the `org.springframework.lang` package.
-By default, types from Java APIs used in Kotlin are recognized as https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types[platform types], for which null-checks are relaxed.
-https://kotlinlang.org/docs/reference/java-interop.html#jsr-305-support[Kotlin support for JSR-305 annotations] and Spring nullability annotations provide null-safety for the whole Spring Data API to Kotlin developers, with the advantage of dealing with `null`-related issues at compile time.
+Although Java does not let you express null safety in its type system, Spring Data API is annotated with https://jcp.org/en/jsr/detail?id=305[JSR-305] tooling friendly annotations declared in the `org.springframework.lang` package.
+By default, types from Java APIs used in Kotlin are recognized as https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types[platform types], for which null checks are relaxed.
+https://kotlinlang.org/docs/reference/java-interop.html#jsr-305-support[Kotlin support for JSR-305 annotations] and Spring nullability annotations provide null safety for the whole Spring Data API to Kotlin developers, with the advantage of dealing with `null` related issues at compile time.
 
+See <<repositories.nullability>> how null safety applies to Spring Data Repositories.
+
+[TIP]
+====
 You can configure JSR-305 checks by adding the `-Xjsr305` compiler flag with the following options: `-Xjsr305={strict|warn|ignore}`.
 
-For kotlin versions 1.1+, the default behavior is the same as `-Xjsr305=warn`.
+For Kotlin versions 1.1+, the default behavior is the same as `-Xjsr305=warn`.
 The `strict` value is required take Spring Data API null-safety into account. Kotlin types inferred from Spring API but should be used with the knowledge that Spring API nullability declaration could evolve, even between minor releases and that more checks may be added in the future.
+====
 
 NOTE: Generic type arguments, varargs, and array elements nullability are not supported yet, but should be in an upcoming release.
 
-See <<repositories.nullability>> how Null-safety applies to Spring Data Repositories.
-
 [[kotlin.mapping]]
 == Object Mapping