Improve on-site payment gateway code documentation.

modules/payment/src/Plugin/Commerce/PaymentGateway/OnsitePaymentGatewayBase.php

@@ -3,7 +3,7 @@
 namespace Drupal\commerce_payment\Plugin\Commerce\PaymentGateway;
 
 /**
- * Provides the base class for onsite payment gateways.
+ * Provides the base class for on-site payment gateways.
  */
 abstract class OnsitePaymentGatewayBase extends PaymentGatewayBase implements OnsitePaymentGatewayInterface {
 

modules/payment/src/Plugin/Commerce/PaymentGateway/OnsitePaymentGatewayInterface.php

@@ -5,7 +5,27 @@ namespace Drupal\commerce_payment\Plugin\Commerce\PaymentGateway;
 use Drupal\commerce_payment\Entity\PaymentInterface;
 
 /**
- * Defines the base interface for onsite payment gateways.
+ * Defines the base interface for on-site payment gateways.
+ *
+ * On-site payment gateways allow the customer to enter credit card details
+ * directly on the site. The details might be safely tokenized before they
+ * reach the server (Braintree, Stripe, etc) or they might be transmitted
+ * directly through the server (PayPal Payments Pro).
+ *
+ * On-site payment flow:
+ * 1) The customer enters checkout.
+ * 2) The PaymentInformation checkout pane shows the "add-payment-method"
+ *    plugin form, allowing the customer to enter their payment details.
+ * 3) On submit, a payment method is created via createPaymentMethod()
+ *    and attached to the customer and the order.
+ * 4) The customer continues checkout, hits the "payment" checkout step.
+ * 5) The PaymentProcess checkout pane calls createPayment(), which charges
+ *    the provided payment method and creates a payment.
+ *
+ * If the payment method could not be charged (for example, because the credit
+ * card's daily limit was breached), the customer is redirected back to the
+ * checkout step that contains the PaymentInformation checkout pane, to provide
+ * a different payment method.
  */
 interface OnsitePaymentGatewayInterface extends PaymentGatewayInterface, SupportsStoredPaymentMethodsInterface {
 

modules/payment/tests/src/Functional/PaymentAdminTest.php

@@ -17,7 +17,7 @@ class PaymentAdminTest extends CommerceBrowserTestBase {
   use StoreCreationTrait;
 
   /**
-   * An onsite payment gateway.
+   * An on-site payment gateway.
    *
    * @var \Drupal\commerce_payment\Entity\PaymentGatewayInterface
    */

modules/payment/tests/src/Functional/PaymentMethodTest.php

@@ -27,7 +27,7 @@ class PaymentMethodTest extends CommerceBrowserTestBase {
   protected $collectionUrl;
 
   /**
-   * An onsite payment gateway.
+   * An on-site payment gateway.
    *
    * @var \Drupal\commerce_payment\Entity\PaymentGatewayInterface
    */

modules/payment_example/config/schema/commerce_payment_example.schema.yml

@@ -10,4 +10,4 @@ commerce_payment.commerce_payment_gateway.plugin.example_offsite_redirect:
   mapping:
     redirect_method:
       type: string
-      label: 'Whether to use POST or 302 Redirect'
+      label: 'Redirect method'

modules/payment_example/src/Plugin/Commerce/PaymentGateway/Onsite.php

@@ -15,11 +15,11 @@ use Drupal\Core\Entity\EntityTypeManagerInterface;
 use Drupal\Core\Form\FormStateInterface;
 
 /**
- * Provides the Onsite payment gateway.
+ * Provides the On-site payment gateway.
  *
  * @CommercePaymentGateway(
  *   id = "example_onsite",
- *   label = "Example (Onsite)",
+ *   label = "Example (On-site)",
  *   display_label = "Example",
  *    forms = {
  *     "add-payment-method" = "Drupal\commerce_payment_example\PluginForm\Onsite\PaymentMethodAddForm",

modules/payment_example/src/Plugin/Commerce/PaymentGateway/OnsiteInterface.php

@@ -9,12 +9,7 @@ use Drupal\commerce_payment\Plugin\Commerce\PaymentGateway\SupportsRefundsInterf
 /**
  * Provides the interface for the example_onsite payment gateway.
  *
- * Onsite payment gateways allow the customer to enter credit card details
- * directly on the site. The details might be safely tokenized before they
- * reach the server (Braintree, Stripe, etc) or they might be transmitted
- * directly through the server (PayPal Payments Pro).
- *
- * The OnsitePaymentGatewayInterface is the base interface which all onsite
+ * The OnsitePaymentGatewayInterface is the base interface which all on-site
  * gateways implement. The other interfaces signal which additional capabilities
  * the gateway has. The gateway plugin is free to expose additional methods,
  * which would be defined below.