Docs: MultiCommand.resultcallback vs MultiCommand.result_callback

[NotTheEconomist]

The commands doc page shows usage of MultiCommand.resultcallback under the header "Multi Command Pipelines" as being a callable itself, that is passed all the associated callbacks with the chained group.

Where do the returned functions go? The chained multicommand can register a callback with MultiCommand.resultcallback() that goes over all these functions and then invoke them.

However, at the bottom of that same doc page, it seems to imply that MultiCommand.result_callback is the same.

Return values of groups can be processed through a MultiCommand.result_callback. This is invoked with the list of all return values in chain mode, or the single return value in case of non chained commands.

The API seems to show that result_callback is an attribute that stores the callback itself, while resultcallback is a function that sets what the callback should be. The naming here is confusing, and it's not clear which one is which. In addition: referring to both of them in the documentation (without clarifying which is which and why) throws an additional spanner into the works.

I recommend a rename for a permanent solution (result_callback -> _result_callback) and more explicit documentation in the short-term.

[jcrotts]

I don't think adding a _ really improves clarity.
The parentheses imply resultcallback is a function, and the dot lookup implies result_callback is an attribute.

How would you suggest the documentation be improved?

[davidism]

I'm renaming the decorator to @result_callback() and the attribute to _result_callback, since it's only used to store the callback, it doesn't appear to be intended to be set directly as a public API. The docs will not mention the attribute and will only mention the renamed decorator.