Docs polishing

Resolves #1313
Resolves #1303

spring-cloud-stream-core-docs/src/main/asciidoc/index.adoc

@@ -1,6 +1,6 @@
 [[spring-cloud-stream-reference]]
 = Spring Cloud Stream Reference Guide
-Sabby Anandan; Marius Bogoevici; Eric Bottard; Mark Fisher; Ilayaperumal Gopinathan; Gunnar Hillert; Mark Pollack; Patrick Peralta; Glenn Renfro; Thomas Risberg; Dave Syer; David Turanski; Janne Valkealahti; Benjamin Klein; Vinicius Carvalho; Oleg Zhurakousky; Jay Bryant
+Sabby Anandan; Marius Bogoevici; Eric Bottard; Mark Fisher; Ilayaperumal Gopinathan; Gunnar Hillert; Mark Pollack; Patrick Peralta; Glenn Renfro; Thomas Risberg; Dave Syer; David Turanski; Janne Valkealahti; Benjamin Klein; Vinicius Carvalho; Gary Russell; Oleg Zhurakousky; Jay Bryant
 :doctype: book
 :toc: left
 :toclevels: 4

spring-cloud-stream-core-docs/src/main/asciidoc/preface.adoc

@@ -26,7 +26,7 @@ Basically, you choose the messaging middleware to which your application binds.
 We recommend using the one you have already installed or feel more comfortable with installing and running.
 Also, as you can see from the Initilaizer screen, there are a few other options you can choose.
 For example, you can choose Gradle as your build tool instead of Maven (the default).
-. In the *Artifact* field, type 'logging-consumer`.
+. In the *Artifact* field, type 'logging-consumer'.
 +
 The value of the *Artifact* field becomes the application name.
 If you chose RabbitMQ for the middleware, your Spring Initializr should now be as follows:
@@ -137,7 +137,7 @@ Spring Cloud Stream introduces a number of new features, enhancements, and chang
 [[spring-cloud-stream-preface-new-features]]
 === New Features and Components
 
-* *Polling Consumers*: Introduction of polled consumers, which let the application can control message processing rates.
+* *Polling Consumers*: Introduction of polled consumers, which lets the application control message processing rates.
 See "`<<spring-cloud-streams-overview-using-polled-consumers>>`" for more details.
 You can also read https://spring.io/blog/2018/02/27/spring-cloud-stream-2-0-polled-consumers[this blog post] for more details.
 
@@ -199,7 +199,7 @@ The following list shows how to add the actuator dependency:
 
 One of the core themes for verion 2.0 is improvements (in both consistency and performance) around content-type negotiation and message conversion.
 The following summary outlines the notable changes and improvements in this area.
-See the "`<<contenttypemanagement>>`" section for more details.
+See the "`<<content-type-management>>`" section for more details.
 Also https://spring.io/blog/2018/02/26/spring-cloud-stream-2-0-content-type-negotiation-and-transformation[this blog post] contains more detail.
 
 * All message conversion is now handled *only* by `MessageConverter` objects.
@@ -221,7 +221,7 @@ As of version 2.0, the following items have been deprecated:
 
 `JavaSerializationMessageConverter` and `KryoMessageConverter` remain for now. However, we plan to move them out of the core packages and support in the future.
 The main reason for this deprecation is to flag the issue that type-based, language-specific serialization could cause in distributed environments, where Producers and Consumers may depend on different JVM versions or have different versions of supporting libraries (that is, Kryo).
-We also wanted to draw the attention to the fact that Consumers and Producers may not be Java-based.
+We also wanted to draw the attention to the fact that Consumers and Producers may not even be Java-based, so polyglot style serialization (i.e., JSON) is better suited.
 
 [[spring-cloud-stream-preface-deprecation-classes-methods]]
 ==== Deprecated Classes and Methods
@@ -240,7 +240,7 @@ public interface Sample {
 }
 ----
 * `HeaderMode.raw`. Use `none`, `headers` or `embeddedHeaders`
-* `ProducerProperties.partitionKeyExtractorClass`. Use `partitionKeyExtractorName` and `ProducerProperties.partitionSelectorClass` in favor of `partitionSelectorName`.
+* `ProducerProperties.partitionKeyExtractorClass` in favor of `partitionKeyExtractorName` and `ProducerProperties.partitionSelectorClass` in favor of `partitionSelectorName`.
 This change ensures that both components are Spring configured and managed and are referenced in a Spring-friendly way.
-* `BinderAwareRouterBeanPostProcessor`. While the component exists, it is no longer a Bean Post Processor and will be renamed in the future.
+* `BinderAwareRouterBeanPostProcessor`. While the component remains, it is no longer a `BeanPostProcessor` and will be renamed in the future.
 * `BinderProperties.setEnvironment(Properties environment)`. Use `BinderProperties.setEnvironment(Map<String, Object> environment)`.

spring-cloud-stream-core-docs/src/main/asciidoc/spring-cloud-stream-overview.adoc

@@ -1648,15 +1648,15 @@ Message<byte[]> toMessage(Object payload, @Nullable MessageHeaders headers);
 As mentioned earlier, the framework already provides a stack of `MessageConverters` to handle most common use cases.
 The following list describes the provided `MessageConverters`, in order of precedence (the first `MessageConverter` that works is used):
 
-. `ApplicationJsonMessageMarshallingConverter`: Variation of the `org.springframework.messaging.converter.MappingJackson2MessageConverter`. Supports conversion of the payload of the `Message` from `String` or `byte[]`.
-. `TupleJsonMessageConverter`: *DEPRECATED* Supports conversion of the payload of the `Message` from `org.springframework.tuple.Tuple`.
-. `ByteArrayMessageConverter`: Supports conversion of the payload of the `Message` from `byte[]` to `byte[]` for cases when `contentType` is set to `application/octet-stream`. It is essentially a pass through and exists primarily for backward compatibility.
+. `ApplicationJsonMessageMarshallingConverter`: Variation of the `org.springframework.messaging.converter.MappingJackson2MessageConverter`. Supports conversion of the payload of the `Message` to/from POJO for cases when `contentType` is `application/json` (DEFAULT).
+. `TupleJsonMessageConverter`: *DEPRECATED* Supports conversion of the payload of the `Message` to/from `org.springframework.tuple.Tuple`.
+. `ByteArrayMessageConverter`: Supports conversion of the payload of the `Message` from `byte[]` to `byte[]` for cases when `contentType` is `application/octet-stream`. It is essentially a pass through and exists primarily for backward compatibility.
 . `ObjectStringMessageConverter`: Supports conversion of any type to a `String` when `contentType` is `text/plain`.
 It invokes Object’s `toString()` method or, if the payload is `byte[]`, a new `String(byte[])`.
 . `JavaSerializationMessageConverter`: *DEPRECATED* Supports conversion based on java serialization when `contentType` is `application/x-java-serialized-object`.
 . `KryoMessageConverter`: *DEPRECATED* Supports conversion based on Kryo serialization when `contentType` is `application/x-java-object`.
 . `JsonUnmarshallingConverter`: Similar to the `ApplicationJsonMessageMarshallingConverter`. It supports conversion of any type when `contentType` is `application/x-java-object`.
-It expects the actual type information to be embedded in the `contentType` as an attribute (for example, `application/x-java-object;type=thingOne.thingTwo.Cat`).
+It expects the actual type information to be embedded in the `contentType` as an attribute (for example, `application/x-java-object;type=foo.bar.Cat`).
 
 When no appropriate converter is found, the framework throws an exception. When that happens, you should check your code and configuration and ensure you did not miss anything (that is, ensure that you provided a `contentType` by using a binding or a header).
 However, most likely, you found some uncommon case (such as a custom `contentType` perhaps) and the current stack of provided `MessageConverters`
@@ -1667,8 +1667,7 @@ does not know how to convert. If that is the case, you can add custom `MessageCo
 
 Spring Cloud Stream exposes a mechanism to define and register additional `MessageConverters`.
 To use it, implement `org.springframework.messaging.converter.MessageConverter`, configure it as a `@Bean`, and annotate it with `@StreamMessageConverter`.
-It is then added to the existing stack of `MessageConverters`.
-The `@StreamMessageConverter` annotation ensures that other other converters that may be present on the application context are not picked up by mistake.
+It is then apended to the existing stack of `MessageConverter`s.
 
 NOTE: It is important to understand that custom `MessageConverter` implementations are added to the head of the existing stack.
 Consequently, custom `MessageConverter` implementations take precedence over the existing ones, which lets you override as well as add to the existing converters.
@@ -1684,7 +1683,7 @@ public static class SinkApplication {
     ...
 
     @Bean
-    @StreamConverter
+    @StreamMessageConverter
     public MessageConverter customMessageConverter() {
         return new MyCustomMessageConverter();
     }