Added some inline comments. The whole event forwarding thing seems to be previously-undocumented API, so it is important we put clear docs :)
It's still not clear to me in which direction the event is forwarded. How about:
Things that I am missing:
BEFORE and AFTER what?
I cannot find a definition for Efl_Callback_Priority in any EO file.
Once they are available, they should be referenced with @ (hyperlink) instead of $ (monospaced font), and using the proper EO syntax, which will probably be @Efl.Callback_Priority.
This is still a bit obscure to me... how about:
So confusing! So the event is unaffected, but it can be intercepted? How about:
$new_obj still emits the original event. Whether this object emits the forwarded event before or after $new_obj can be controlled by the $priority parameter (see below).
Wow, I didn't know @cref. What does it do?
Do not change the name of the thing! We have been calling it "event forwarder", so keep calling it "event forwarder" (not "redirection handler").
I would call this original_obj, and the comment should be [[The object which emits the initial event]]
Change my previous comments accordingly if you call this parameter something other than new_obj.
I am removing completely the reference to event interception as this is confusing and unrelated to forwarder (all events can be blocked from propagating there event further with efl_event_callback_stop).
To my understanding @cref is a const pointer to an object that the caller keep control of after the call. I would for example not expect this call to keep a reference somewhere to desc once the call is done. Arguably, this is one of this things where onle @q66 and @felipealmeida will be able to give the exact definition.
It also imply @in as const pointer can not be modified and so can't be an out.