Unclear docs: "onSuccess" behavior

[everdimension]

Hi!

I'm trying to understand the motivation to use the onSuccess option for useMutation

The given description doesn't provide me with enough information.

Assumption

My initial assumption was the onSuccess handles an edge case:
If mutationFn resolves after the component has been unmounted, it will not be invoked. Therefore, it would be safe to call imperative UI code that's not crucial for the mutation, e.g. something like navigateBack() after the mutation is done.

I looked at the code and it seems that onSuccess is always called after mutationFn, so this assumption is false.

Docs should remove guesswork

Therefore, I can only make other guesses as to why this helper exists. Ideally, this would be explained in the method description.
So far, I don't see why I can't call the same code I would call in onSuccess inside mutationFn instead.
I assume the reason may have to do something with global code listening to queryClient mutations, but I'm not sure.

Let's add a more clear description?