From: Eileen McNaughton <eileen@fuzion.co.nz>
Date: Sat, 4 Apr 2015 04:39:10 +0000 (+1300)
Subject: Comment additions & fixes
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=003ca72987b9914eb6b24e154738374547576a0c;p=civicrm-core.git

Comment additions & fixes
---

diff --git a/CRM/Price/BAO/PriceSet.php b/CRM/Price/BAO/PriceSet.php
index 6371a749f5..06cafe44ac 100644
--- a/CRM/Price/BAO/PriceSet.php
+++ b/CRM/Price/BAO/PriceSet.php
@@ -481,11 +481,14 @@ WHERE     ct.id = cp.financial_type_id AND
    * An array containing price set details (including price fields) is returned
    *
    * @param int $setID
+   *   Price Set ID.
    * @param bool $required
+   *   Appears to have no effect based on reading the code.
    * @param bool $validOnly
+   *   Should only fields where today's date falls within the valid range be returned?
    *
    * @return array
-   *   array consisting of field details
+   *   Array consisting of field details
    */
   public static function getSetDetail($setID, $required = TRUE, $validOnly = FALSE) {
     // create a new tree
@@ -575,7 +578,9 @@ WHERE  id = %1";
   }
 
   /**
-   * Get the Price Field ID. We call this function when more than one being present would represent an error
+   * Get the Price Field ID.
+   *
+   * We call this function when more than one being present would represent an error
    * starting format derived from current(CRM_Price_BAO_PriceSet::getSetDetail($priceSetId))
    * @param array $priceSet
    *
@@ -607,11 +612,17 @@ WHERE  id = %1";
 
 
   /**
+   * Initiate price set such that various non-BAO things are set on the form.
+   *
+   * This function is not really a BAO function so the location is misleading.
+   *
    * @param CRM_Core_Form $form
    * @param int $id
+   *   Form entity id.
    * @param string $entityTable
    * @param bool $validOnly
    * @param int $priceSetId
+   *   Price Set ID
    *
    * @return bool|false|int|null
    */
@@ -708,10 +719,21 @@ WHERE  id = %1";
   }
 
   /**
+   * Get line item purchase information.
+   *
+   * This function takes the input parameters and interprets out of it what has been purchased.
+   *
    * @param $fields
+   *   This is the output of the function CRM_Price_BAO_PriceSet::getSetDetail($priceSetID, FALSE, FALSE);
+   *   And, it would make sense to introduce caching into that function and call it from here rather than
+   *   require the $fields array which is passed from pillar to post around the form in order to pass it in here.
    * @param array $params
+   *   Params reflecting form input e.g with fields 'price_5' => 7, 'price_8' => array(7, 8)
    * @param $lineItem
+   *   Line item array to be altered.
    * @param string $component
+   *   This parameter appears to only be relevant to determining whether memberships should be auto-renewed.
+   *   (and is effectively a boolean for 'is_membership' which could be calculated from the line items.)
    */
   public static function processAmount(&$fields, &$params, &$lineItem, $component = '') {
     // using price set
@@ -973,15 +995,20 @@ WHERE  id = %1";
   }
 
   /**
-   * Check the current Membership
-   * having end date null.
+   * Check the current Membership having end date null.
+   *
+   * @param array $options
+   * @param int $userid
+   *   Probably actually contact ID.
+   *
+   * @return bool
    */
   public static function checkCurrentMembership(&$options, $userid) {
     if (!$userid || empty($options)) {
       return;
     }
     static $_contact_memberships = array();
-    $checklifetime = FALSE;
+    $checkLifetime = FALSE;
     foreach ($options as $key => $value) {
       if (!empty($value['membership_type_id'])) {
         if (!isset($_contact_memberships[$userid][$value['membership_type_id']])) {
@@ -990,11 +1017,11 @@ WHERE  id = %1";
         $currentMembership = $_contact_memberships[$userid][$value['membership_type_id']];
         if (!empty($currentMembership) && empty($currentMembership['end_date'])) {
           unset($options[$key]);
-          $checklifetime = TRUE;
+          $checkLifetime = TRUE;
         }
       }
     }
-    if ($checklifetime) {
+    if ($checkLifetime) {
       return TRUE;
     }
     else {
@@ -1322,6 +1349,9 @@ GROUP BY     mt.member_of_contact_id";
    * Check if price set id provides option for
    * user to select both auto-renew and non-auto-renew memberships
    *
+   * @param int $id
+   *
+   * @return bool
    */
   public static function checkMembershipPriceSet($id) {
     $query