[improve][doc] Improve doc for `maxTotalReceiverQueueSizeAcrossPartit…

…ions` and `receiverQueueSize` of ConsumerBuilder (apache#21841)

Fixes apache#21838 

### Motivation

From the implementation, the maximum number of messages actually cached by multi-topics consumer is approximately receiverQueueSize+maxTotalReceiverQueueSizeAcrossPartitions.This seems to go against the case described in the documentation.

Please see more details in apache#21838

### Modifications

- Improve the doc to clarify the correct behavior of `maxTotalReceiverQueueSizeAcrossPartitions`

pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ConsumerBuilder.java

@@ -345,6 +345,10 @@ public interface ConsumerBuilder<T> extends Cloneable {
      * application calls {@link Consumer#receive()}. Using a higher value can potentially increase consumer
      * throughput at the expense of bigger memory utilization.
      *
+     * <p>For the consumer that subscribes to the partitioned topic, the parameter
+     * {@link ConsumerBuilder#maxTotalReceiverQueueSizeAcrossPartitions} also affects
+     * the number of messages accumulated in the consumer.
+     *
      * <p><b>Setting the consumer queue size as zero</b>
      * <ul>
      * <li>Decreases the throughput of the consumer by disabling pre-fetching of messages. This approach improves the
@@ -409,8 +413,13 @@ public interface ConsumerBuilder<T> extends Cloneable {
      * of messages that a consumer can be pushed at once from a broker, across all
      * the partitions.
      *
-     * @param maxTotalReceiverQueueSizeAcrossPartitions
-     *            max pending messages across all the partitions
+     * <p>This setting is applicable only to consumers subscribing to partitioned topics. In such cases, there will
+     * be multiple queues for each partition and a single queue for the parent consumer. This setting controls the
+     * queues of all partitions, not the parent queue. For instance, if a consumer subscribes to a single partitioned
+     * topic, the total number of messages accumulated in this consumer will be the sum of
+     * {@link #receiverQueueSize(int)} and maxTotalReceiverQueueSizeAcrossPartitions.
+     *
+     * @param maxTotalReceiverQueueSizeAcrossPartitions max pending messages across all the partitions
      * @return the consumer builder instance
      */
     ConsumerBuilder<T> maxTotalReceiverQueueSizeAcrossPartitions(int maxTotalReceiverQueueSizeAcrossPartitions);