GH-2447: Publisher Confirms/Returns Doc Polishing

Resolves #2447

Author: garyrussell

spring-rabbit/src/main/java/org/springframework/amqp/rabbit/connection/CorrelationData.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2022 the original author or authors.
+ * Copyright 2002-2023 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -96,7 +96,7 @@ public CompletableFuture<Confirm> getFuture() {
 
 	/**
 	 * Get the returned message and metadata, if any. Guaranteed to be populated before
-	 * the future is set.
+	 * the future is completed.
 	 * @return the {@link ReturnedMessage}.
 	 * @since 2.3.3
 	 */

src/reference/asciidoc/amqp.adoc

@@ -851,7 +851,7 @@ When such a channel is obtained, the client can register a `PublisherCallbackCha
 The `PublisherCallbackChannel` implementation contains logic to route a confirm or return to the appropriate listener.
 These features are explained further in the following sections.
 
-See also `simplePublisherConfirms` in <<scoped-operations>>.
+See also <<template-confirms>> and `simplePublisherConfirms` in <<scoped-operations>>.
 
 TIP: For some more background information, see the blog post by the RabbitMQ team titled https://www.rabbitmq.com/blog/2011/02/10/introducing-publisher-confirms/[Introducing Publisher Confirms].
 
@@ -1278,6 +1278,8 @@ The following example shows how to configure a `CorrelationData` instance:
 CorrelationData cd1 = new CorrelationData();
 this.templateWithConfirmsEnabled.convertAndSend("exchange", queue.getName(), "foo", cd1);
 assertTrue(cd1.getFuture().get(10, TimeUnit.SECONDS).isAck());
+ReturnedMessage = cd1.getReturn();
+...
 ----
 ====
 
@@ -1286,8 +1288,15 @@ The `Confirm` object is a simple bean with 2 properties: `ack` and `reason` (for
 The reason is not populated for broker-generated `nack` instances.
 It is populated for `nack` instances generated by the framework (for example, closing the connection while `ack` instances are outstanding).
 
-In addition, when both confirms and returns are enabled, the `CorrelationData` is populated with the returned message, as long as the `CorrelationData` has a unique `id`; this is always the case, by default, starting with version 2.3.
-It is guaranteed that the returned message is set before the future is set with the `ack`.
+In addition, when both confirms and returns are enabled, the `CorrelationData` `return` property is populated with the returned message, if it couldn't be routed to any queue.
+It is guaranteed that the returned message property is set before the future is set with the `ack`.
+`CorrelationData.getReturn()` returns a `ReturnMessage` with properties:
+
+* message (the returned message)
+* replyCode
+* replyText
+* exchange
+* routingKey
 
 See also <<scoped-operations>> for a simpler mechanism for waiting for publisher confirms.