GH-1621: Doc/Javadoc Polishing

Author: garyrussell

spring-kafka/src/main/java/org/springframework/kafka/listener/ContainerProperties.java

@@ -311,6 +311,10 @@ public void setMessageListener(Object messageListener) {
 	 * Ignored when transactions are being used. Transactional consumers commit offsets
 	 * with semantics equivalent to {@code RECORD} or {@code BATCH}, depending on
 	 * the listener type.
+	 * However, setting it to {@code MANUAL} will provide access to an
+	 * {@code Acknowledgement} in the listener; when calling its
+	 * {@code nack(index, sleeptime)} method, the container will send the offsets of
+	 * the succcessfully processed records in the batch to the transaction.
 	 * @param ackMode the {@link AckMode}; default BATCH.
 	 * @see #setTransactionManager(PlatformTransactionManager)
 	 */

src/reference/asciidoc/kafka.adoc

@@ -1145,6 +1145,8 @@ Starting with version 2.3, the `Acknowledgment` interface has two additional met
 The first one is used with a record listener, the second with a batch listener.
 Calling the wrong method for your listener type will throw an `IllegalStateException`.
 
+NOTE: If you want to commit a partial batch, using `nack()`, When using transactions, set the `AckMode` to `MANUAL`; invoking `nack()` will send the offsets of the successfully processed records to the transaction.
+
 IMPORTANT: `nack()` can only be called on the consumer thread that invokes your listener.
 
 With a record listener, when `nack()` is called, any pending offsets are committed, the remaing records from the last poll are discarded, and seeks are performed on their partitions so that the failed record and unprocessed records are redelivered on the next `poll()`.