[Bug] The javadoc of ConsumerBuilder.isAckReceiptEnabled is not consistent, it references ack timeout and redelivery which isn't related to ack receipt

[lhotari]

Search before asking

• I searched in the issues and found nothing similar.

Read release policy

• I understand that unsupported versions don't get bug fixes. I will attempt to reproduce the issue on a supported version of Pulsar client and Pulsar broker.

Version

any released version, master branch

Minimal reproduce step

The javadoc of ConsumerBuilder.isAckReceiptEnabled is not consistent, it references ack timeout and redelivery which isn't related to ack receipt at all:

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

Lines 200 to 208 in 10f4e02

	/**
	* Acknowledgement returns receipt, but the message is not re-sent after getting receipt.
	*
	* Configure the acknowledgement timeout mechanism to redeliver the message if it is not acknowledged after
	* ackTimeout, or to execute a timer task to check the acknowledgement timeout messages during every
	* ackTimeoutTickTime period.
	*
	* @param isAckReceiptEnabled {@link Boolean} enables acknowledgement for receipt
	* @return the consumer builder instance

What did you expect to see?

There should be a proper explanation of why ack receipt is useful and what considerations are needed when using it.

One reason to enable ack receipt feature is to ensure that acknowledgements reach the server. The current assumption is that there isn't any automatic acknowledgement retry logic, but this is to be confirmed when documenting the feature.
When using this feature, it's recommended to use acknowledgeAsync. Using acknowledge would cause performance issues for most applications since it introduces a round trip to the server and would prevent pipelining (having multiple messages in-flight). In some usecases that might be desirable.

What did you see instead?

Misleading description

Anything else?

No response

Are you willing to submit a PR?

• I'm willing to submit a PR!

[lhotari]

Opened an ack receipt related bug report #23261

[lhotari]

There's a separate proposal "PIP-377: Automatic retry for failed acknowledgements", #23267 (rendered doc) . Discussion thread https://lists.apache.org/thread/7sg7hfv9dyxto36dr8kotghtksy1j0kr