KAFKA-13810: Document behavior of KafkaProducer.flush() w.r.t callbac…

…ks (apache#12042)

Reviewers: Luke Chen <[email protected]>, Andrew Eugene Choi <[email protected]>

clients/src/main/java/org/apache/kafka/clients/producer/KafkaProducer.java

@@ -1154,7 +1154,8 @@ private void ensureValidRecordSize(int size) {
     /**
      * Invoking this method makes all buffered records immediately available to send (even if <code>linger.ms</code> is
      * greater than 0) and blocks on the completion of the requests associated with these records. The post-condition
-     * of <code>flush()</code> is that any previously sent record will have completed (e.g. <code>Future.isDone() == true</code>).
+     * of <code>flush()</code> is that any previously sent record will have completed (e.g. <code>Future.isDone() == true</code>
+     * and callbacks passed to {@link #send(ProducerRecord,Callback)} have been called).
      * A request is considered completed when it is successfully acknowledged
      * according to the <code>acks</code> configuration you have specified or else it results in an error.
      * <p>