Document differences in behavior of Circuit.insert(pos, *ops) vs Circuit.insert(pos, Moment(*ops))

[pavoljuhas]

Describe the issue

Implementation of #7829 established a more consistent behavior of Circuit.insert and Circuit.append over a different InsertStrategy choices. When insert or append methods add a list of operations they prevent an overlap of measurement and control keys and instead add new moment(s) as needed. However, moments with an overlapping measurement keys and measurement-vs-control keys can be still created by using an explicit cirq.Moment(cirq.M(q0, key="m"), cirq.M(q1, key="m")) call. The support for the latter constructions is a requirement for QEC experiments, #8131.

• We should verify that docstrings to Circuit insert, append, __init__ are consistent with the above behavior and clarify them as needed. The guidance for non-expert users should be to avoid overlapping keys and use either distinct keys or a multi-qubit measurements cirq.M(q0, q1, ..., qN, key="m") instead. Expert users can call cirq.Moment to pack operations with possibly overlapping keys as wanted with an assumption they know what they do.
• We should verify documentation colabs and tutorials are still up to date after #7829
• We should ensure there are unit tests for creation of moments with overlapping keys and their insertion to a circuit via insert, append so it is more apparent that such use is desired and not a legacy leftover.

Tell us the version of Cirq where this happens

1.7.0.dev0 at 6922063