Polish reference documentation

src/docs/asciidoc/core/core-null-safety.adoc

@@ -2,38 +2,8 @@
 = Null-safety
 
 Although Java does not allow to express null-safety with its type system, Spring Framework
-now provides annotations to declare nullability of APIs and fields.
-
-Spring Framework leverages itself these annotations, but they can also be used in any Spring based
-Java project to declare null-safe APIs and optionally null-safe fields. Nullability of
-types used inside method bodies is outside of the scope of this feature.
-
-These annotations are meta-annotated with https://jcp.org/en/jsr/detail?id=305[JSR 305]
-annotations (a dormant JSR but supported by tools like IntelliJ IDEA) to provide useful
-warnings to Java developers related to null-safety in order to avoid `NullPointerException`
-at runtime. JSR 305 meta-annotations allows tooling vendors to provide null-safety support
-in a generic way, without having to hard-code support for Spring annotations.
-
-[NOTE]
-====
-It is not necessary nor recommanded to have JSR 305 dependency in project classpath to
-take advatange of Spring null-safe API. Only projects like
-Spring-based libraries using null-safety annotations in their codebase should add
-`com.google.code.findbugs:jsr305:3.0.2` with `compileOnly` Gradle configuration or Maven
-`provided` scope to avoid compile warnings.
-====
-
-They are also used by Kotlin which supports natively
-https://kotlinlang.org/docs/reference/null-safety.html[null-safety]. More details are
-available in <<kotlin#null-safety,Kotlin support documentation>>.
-
-[NOTE]
-====
-Other libraries like Reactor or Spring Data leverage these annotations as well to provide
-null-safe APIs.
-====
-
-The following annotations are provided in the `org.springframework.lang` package:
+now provides following annotations in the `org.springframework.lang` package to declare
+nullability of APIs and fields:
 
  * {api-spring-framework}/lang/NonNull.html[`@NonNull`] annotation where specific parameter,
  return value or field cannot be `null` (not needed on parameter and return value
@@ -45,8 +15,39 @@ The following annotations are provided in the `org.springframework.lang` package
  * {api-spring-framework}/lang/NonNullFields.html[`@NonNullFields`] annotation at package
  level declares non-null as the default behavior for fields.
 
+Spring Framework leverages itself these annotations, but they can also be used in any Spring based
+Java project to declare null-safe APIs and optionally null-safe fields. Generic type arguments,
+varargs and array elements nullability are not supported yet, but should be in an upcoming
+release, see https://jira.spring.io/browse/SPR-15942[SPR-15942] for up-to-date information.
+Nullability declaration are expected to be fine-tuned between Spring Framework release,
+including minor ones. Nullability of types used inside method bodies is outside of the
+scope of this feature.
+
 [NOTE]
 ====
-Generic type arguments, varargs and array elements nullability are not supported yet,
-see https://jira.spring.io/browse/SPR-15942[SPR-15942] for up-to-date information.
-====
+Libraries like Reactor or Spring Data provide null-safe APIs leveraging this feature.
+====
+
+== Use cases
+
+In addition to providing an explicit declaration for Spring Framework API nullability,
+these annotation can be used by IDE (such as IDEA or Eclipse) to provide useful
+warnings to Java developers related to null-safety in order to avoid `NullPointerException`
+at runtime.
+
+They are also used to make Spring API null-safe in Kotlin projects since Kotlin natively
+supports https://kotlinlang.org/docs/reference/null-safety.html[null-safety]. More details
+are available in <<kotlin#null-safety,Kotlin support documentation>>.
+
+== JSR 305 meta-annotations
+
+Spring annotations are meta-annotated with https://jcp.org/en/jsr/detail?id=305[JSR 305]
+annotations (a dormant but widely spread JSR). JSR 305 meta-annotations allows tooling vendors
+like IDEA or Kotlin to provide null-safety support in a generic way, without having to hard-code
+support for Spring annotations.
+
+It is not necessary nor recommended to add JSR 305 dependency in project classpath to
+take advantage of Spring null-safe API. Only projects like
+Spring-based libraries using null-safety annotations in their codebase should add
+`com.google.code.findbugs:jsr305:3.0.2` with `compileOnly` Gradle configuration or Maven
+`provided` scope to avoid compile warnings.

src/docs/asciidoc/kotlin.adoc

@@ -95,27 +95,26 @@ 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://github.com/Kotlin/KEEP/blob/jsr-305/proposals/jsr-305-custom-nullability-qualifiers.md[Kotlin support for JSR 305 annotations]
-available as of https://blog.jetbrains.com/kotlin/2017/08/kotlin-1-1-4-is-out/[1.1.4 release]
 + Spring nullability annotations provide null-safety for the whole Spring Framework API to Kotlin developers,
 with the advantage of dealing with `null` related issues at compile time.
 
 [NOTE]
 ====
-Other libraries like Reactor and Spring Data leverage these annotations as well to provide
-null-safe APIs for Kotlin developers.
+Libraries like Reactor or Spring Data provide null-safe APIs leveraging this feature.
 ====
 
 The JSR 305 checks can be configured by adding the `-Xjsr305` compiler flag with the following
 options: `-Xjsr305={strict|warn|ignore}`.
 
-For kotlin versions 1.1.50+/1.2, the default behavior is the same to `-Xjsr305=warn`. The
-`strict` value should be considered experimental (Spring API nullability could evolve and
-more checks may be added in the future).
+For kotlin versions 1.1.50+, the default behavior is the same to `-Xjsr305=warn`. The
+`strict` value should be considered experimental (Spring API nullability declaration could
+evolve even between minor releases and more checks may be added in the future).
 
 [NOTE]
 ====
 Generic type arguments, varargs and array elements nullability are not supported yet,
-see https://jira.spring.io/browse/SPR-15942[SPR-15942] for up-to-date information.
+but should be in an upcoming release, see https://jira.spring.io/browse/SPR-15942[SPR-15942]
+for up-to-date information.
 ====
 
 [[classes-interfaces]]
@@ -127,7 +126,7 @@ with default values.
 
 Kotlin parameter names are recognized via a dedicated `KotlinReflectionParameterNameDiscoverer`
 which allows finding interface method parameter names without requiring the Java 8 `-parameters`
-compiler flag enabled during compliation.
+compiler flag enabled during compilation.
 
 https://github.com/FasterXML/jackson-module-kotlin[Jackson Kotlin module] which is required
 for serializing / deserializing JSON data is automatically registered when
@@ -390,9 +389,9 @@ plugin.
 
 [NOTE]
 ====
-As of Kay release train, Spring Data supports Kotlin immutable class instances and should
-not require `kotlin-noarg` plugin if the underlying persistence solution allows it
-(for example with MongoDB).
+As of Kay release train, Spring Data supports Kotlin immutable class instances
+and should not require `kotlin-noarg` plugin if the module leverages Spring Data object
+mapping (like with MongoDB, Redis, Cassandra, etc.).
 ====
 
 === Injecting dependencies