[improve][doc] Note that --timeout-ms also sets the negative ack redelivery delay

[david-streamlio]

Motivation

FunctionConfigUtils.convert sets a function's negative-ack redelivery delay from its message timeout:

if (functionConfig.getTimeoutMs() != null) {
    sourceSpec.setTimeoutMs(functionConfig.getTimeoutMs());
    // We use negative acks for fast tracking failures
    sourceSpec.setNegativeAckRedeliveryDelayMs(functionConfig.getTimeoutMs());
}

So --timeout-ms silently drives two settings: the unacknowledged-message timeout and the delay before a negatively acknowledged message is redelivered.

Nothing in the docs says so. The timeoutMs row documents only the message timeout, and negativeAckRedeliveryDelayMs is not a function-level option at all — there is no FunctionConfig field and no flag in CmdFunctions. The sink equivalent, --negative-ack-redelivery-delay-ms, is documented in io-cli.md, which makes the absence for functions look like an oversight rather than a deliberate coupling.

The practical effect: someone lowering --timeout-ms to fail fast also shortens redelivery, and someone raising it for a slow downstream also delays every retry. Neither is discoverable from the current description.

Modifications

Amend the timeoutMs row to state the coupling, and record how the three runtimes differ:

Runtime	Message timeout	Negative-ack redelivery delay
Java	yes	yes
Python	yes	no (#26411)
Go	no	yes

• Java — PulsarSource calls both ackTimeout(...) and negativeAckRedeliveryDelay(...).
• Python — python_instance.py passes unacked_messages_timeout_ms but never the redelivery delay, so the client default of 60 s always applies.
• Go — instance.go builds ConsumerOptions with NackRedeliveryDelay and no ack timeout.

Versioned docs

The coupling is present in every supported release, so docs/ plus 5.0.x, 4.2.x, and 4.0.x.

The runtime line there is not a copy of the one in docs/. apache/pulsar#26415 gave the Go runtime the negative-ack redelivery delay on master only, and it is in none of these releases; the Go runtime has never applied an ack timeout either, its ConsumerOptions carrying neither field. So the versioned copies say Go applies neither setting, where docs/ says it applies the redelivery delay.

Follow-up

apache/pulsar#26413 makes the Python runtime honour the redelivery delay. When it lands, the Python entry becomes "yes" and the #26411 reference comes out — a one-line change I will send separately rather than describing behaviour that has not shipped.

I have deliberately left that PR labelled doc-not-needed. The gap documented here predates it and is equally true of Java today, so it seemed wrong to make an unrelated fix carry it.

Documentation

This is the documentation change.