Document operator| vs operator>> and deprecate/remove non-preferred operators

[CodingCanuck]

Prior to #387, eventuals were composed like this:
return Foo() | Bar();

After that PR, they may now additionally be composed like this:
return Foo() >> Bar();

Both of these operators lack documentation as to what they do or how they're similar / different: https://github.com/3rdparty/eventuals/blame/00f4ac7fe5a3ebf1749845274de5b23e7aca2806/eventuals/compose.h#L105-L129

I thought I remembered @benh saying that there was maybe some difference between these two operators as to how they affect evaluation order within expressions or across expressions, but I see no discussion of that (or other motivations) on the PR.

Let's document the difference between these two operators. If one is preferred, we should deprecate the non-preferred option, port callers to the new style, and delete the old operator.

@benh and @nizamutdinovb are probably best suited to clarify how these operators do and don't differ and whether one is preferred.

[CodingCanuck]

I tried reading https://en.cppreference.com/w/cpp/language/eval_order to understand if either of these operators had any different guarantees in terms of operand evaluation order. I think this is maybe the relevant bit: https://en.cppreference.com/w/cpp/language/eval_order#Sequenced-before_rules_.28since_C.2B.2B11.29

19. In a shift operator expression E1 << E2 and E1 >> E2, every value computation and side-effect of E1 is sequenced before every value computation and side effect of E2

If I'm reading that correctly, that means for all shift operators including overloaded shift operators (e.g. eventuals' operator>>), that guarantees that the left operands of >> are evaluated before the right operands.

If that's true, then I'd guess that we want to deprecate operator| and move to operator>>.

[NikitaNikolaenko]

Yes, the reason why we implemented operator>> is because of evaluation order.

[CodingCanuck]

Note that https://github.com/reboot-dev/respect/pull/693#event-7047015659 removes uses of the old operator| in client repos.