Expand code documentation for off-site payment gateways

Note that if this is the case (that payment gateways should not update the order status), that #2934647: The order can stay unplaced after an offsite payment.

#2934647: The order can stay unplaced after an offsite payment has landed, let's add those docs now.

Now that #3009962: Invalid step ID "" passed to redirectToStep() in PaymentCheckoutController->returnPage is in, we also need to document that onReturn() will be skipped if onNotify() resulted in a placed order.

Here's a patch.

And here's the entire OffsitePaymentGatewayInterface docblock for context:

 * Defines the base interface for off-site payment gateways.
 *
 * Off-site payment flow:
 * 1) Customer hits the "payment" checkout step.
 * 2) The PaymentProcess checkout pane shows the "offsite-payment" plugin form.
 * 3) The plugin form performs a redirect or shows an iFrame.
 * 4) The customer provides their payment details to the payment provider.
 * 5) The payment provider redirects the customer back to the return url.
 * 6) A payment is created in either onReturn() or onNotify().
 *
 * If the payment provider supports asynchronous notifications (IPNs), then
 * creating the payment in onNotify() is preferred, since it is guaranteed to
 * be called even if the customer does not return to the site.
 *
 * Note that onReturn() will be skipped if onNotify() was called before the
 * customer returned to the site, completing the payment process and
 * placing the order.
 *
 * If the customer declines to provide their payment details, and cancels
 * the payment at the payment provider, they will be redirected back to the
 * cancel url.

Now with 100% more patch!

+++ b/modules/payment/src/Plugin/Commerce/PaymentGateway/OffsitePaymentGatewayInterface.php
@@ -40,6 +44,11 @@ interface OffsitePaymentGatewayInterface extends PaymentGatewayInterface, Suppor
+   * the parent order should not be touched. The order state is updated

The parent order should not be touched whatsoever or it should not be placed/transition should not be fired?

I'm wondering if it is strictly forbidden for payments to modify the order, even if only to set some metadata on the order itself.

I'll change "should not be touched" to "does not need to be touched", since it's not forbidden.

Fixed #8 and committed. Thanks, everyone.