core.async docstrings for `take!` and `put!` not clear on impact of `on-caller?`

Question

The core.async docstrings for take! and put! currently only state that, if on-caller? is true, fn1 is called on the calling thread when the value is immediately available/the put is immediately accepted. They do not make clear that, when the value is not immediately available/the put is not immediately accepted, on-caller? also determines whether fn1 is called on the then 'calling' thread or the dispatch thread pool. It is only indicated that fn1 may be run in a fixed-size dispatch thread pool' in both cases. The docstring of clojure.core.async.impl.dispatch/run does refer to the :on-caller? meta. Is this analysis correct? If so, wouldn't it make sense to add this information in the docstrings?

Answer 1

Including the docstring here for reference:

Asynchronously takes a val from port, passing to fn1. Will pass nil if
closed. If on-caller? (default true) is true, and value is immediately
available, will call fn1 on calling thread.

fn1 may be run in a fixed-size dispatch thread pool and should not
perform blocking IO, including core.async blocking ops (those that end
in !!).

The docstring is promising what will will happen if on-caller? is true and the value is immediately available. When those conditions are not met, there are no promises being made. The actual implementation has changed over time and may change again to optimize performance.