From 03b9d60b8eb2c475c9447a1eb7117b8d14aab65a Mon Sep 17 00:00:00 2001
From: Shamim Rezaie <shamim@moodle.com>
Date: Tue, 9 Feb 2021 17:59:28 +1100
Subject: [PATCH] MDL-70287 core_payment: Improving existing and missing
 phpdocs

---
 .../fee/classes/payment/service_provider.php  |  2 +-
 payment/classes/helper.php                    | 30 ++++++++++---------
 .../local/callback/service_provider.php       |  9 ++++--
 3 files changed, 24 insertions(+), 17 deletions(-)

diff --git a/enrol/fee/classes/payment/service_provider.php b/enrol/fee/classes/payment/service_provider.php
index cab7b0f427508..02497be1cfe9b 100644
--- a/enrol/fee/classes/payment/service_provider.php
+++ b/enrol/fee/classes/payment/service_provider.php
@@ -37,7 +37,7 @@ class service_provider implements \core_payment\local\callback\service_provider
      * Callback function that returns the enrolment cost and the accountid
      * for the course that $instanceid enrolment instance belongs to.
      *
-     * @param string $paymentarea
+     * @param string $paymentarea Payment area
      * @param int $instanceid The enrolment instance id
      * @return \core_payment\local\entities\payable
      */
diff --git a/payment/classes/helper.php b/payment/classes/helper.php
index b5dc3c17471d0..39c4343d82923 100644
--- a/payment/classes/helper.php
+++ b/payment/classes/helper.php
@@ -60,9 +60,9 @@ public static function get_supported_currencies(): array {
     /**
      * Returns the list of gateways that can process payments in the given currency.
      *
-     * @param string $component
-     * @param string $paymentarea
-     * @param int $itemid
+     * @param string $component Name of the component that the paymentarea and itemid belong to
+     * @param string $paymentarea Payment area
+     * @param int $itemid An identifier that is known to the component
      * @return string[]
      */
     public static function get_available_gateways(string $component, string $paymentarea, int $itemid): array {
@@ -165,7 +165,9 @@ public static function gateways_modal_link_params(string $component, string $pay
     }
 
     /**
-     * @param string $component
+     * Get the name of the service provider class
+     *
+     * @param string $component The component
      * @return string
      * @throws \coding_exception
      */
@@ -185,8 +187,8 @@ private static function get_service_provider_classname(string $component) {
     /**
      * Asks the payable from the related component.
      *
-     * @param string $component Name of the component that the itemid belongs to
-     * @param string $paymentarea
+     * @param string $component Name of the component that the paymentarea and itemid belong to
+     * @param string $paymentarea Payment area
      * @param int $itemid An internal identifier that is used by the component
      * @return local\entities\payable
      */
@@ -199,10 +201,10 @@ public static function get_payable(string $component, string $paymentarea, int $
     /**
      * Returns the gateway configuration for given component and gateway
      *
-     * @param string $component
-     * @param string $paymentarea
-     * @param int $itemid
-     * @param string $gatewayname
+     * @param string $component Name of the component that the paymentarea and itemid belong to
+     * @param string $paymentarea Payment area
+     * @param int $itemid An identifier that is known to the component
+     * @param string $gatewayname The gateway name
      * @return array
      * @throws \moodle_exception
      */
@@ -225,8 +227,8 @@ public static function get_gateway_configuration(string $component, string $paym
      *
      * @uses \core_payment\local\callback\service_provider::deliver_order()
      *
-     * @param string $component Name of the component that the itemid belongs to
-     * @param string $paymentarea
+     * @param string $component Name of the component that the paymentarea and itemid belong to
+     * @param string $paymentarea Payment area
      * @param int $itemid An internal identifier that is used by the component
      * @param int $paymentid payment id as inserted into the 'payments' table, if needed for reference
      * @param int $userid The userid the order is going to deliver to
@@ -244,8 +246,8 @@ public static function deliver_order(string $component, string $paymentarea, int
      * Each payment gateway may then store the additional information their way.
      *
      * @param int $accountid Account id
-     * @param string $component Name of the component that the itemid belongs to
-     * @param string $paymentarea
+     * @param string $component Name of the component that the paymentarea and itemid belong to
+     * @param string $paymentarea Payment area
      * @param int $itemid An internal identifier that is used by the component
      * @param int $userid Id of the user who is paying
      * @param float $amount Amount of payment
diff --git a/payment/classes/local/callback/service_provider.php b/payment/classes/local/callback/service_provider.php
index 20fe0725e1909..ba91668db6f5e 100644
--- a/payment/classes/local/callback/service_provider.php
+++ b/payment/classes/local/callback/service_provider.php
@@ -35,14 +35,19 @@
 interface service_provider {
 
     /**
-     * @param string $paymentarea
+     * Callback function that returns the cost of the given item in the specified payment area,
+     * along with the accountid that payments are paid to.
+     *
+     * @param string $paymentarea Payment area
      * @param int $itemid An identifier that is known to the plugin
      * @return \core_payment\local\entities\payable
      */
     public static function get_payable(string $paymentarea, int $itemid): \core_payment\local\entities\payable;
 
     /**
-     * @param string $paymentarea
+     * Callback function that delivers what the user paid for to them.
+     *
+     * @param string $paymentarea Payment area
      * @param int $itemid An identifier that is known to the plugin
      * @param int $paymentid payment id as inserted into the 'payments' table, if needed for reference
      * @param int $userid The userid the order is going to deliver to