From b6df6c1b2ff60b7b46698485aa6309d162f34404 Mon Sep 17 00:00:00 2001
From: Eileen McNaughton <emcnaughton@wikimedia.org>
Date: Fri, 20 May 2022 10:17:56 +1200
Subject: [PATCH] Improve comment blocks for mapper

---
 CRM/Contact/Import/Parser/Contact.php              | 11 ++++++++++-
 .../CRM/Contact/Import/Form/MapFieldTest.php       |  4 +++-
 .../CRM/Contact/Import/Parser/ContactTest.php      | 14 +++++++++++---
 3 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/CRM/Contact/Import/Parser/Contact.php b/CRM/Contact/Import/Parser/Contact.php
index 67047e7812..4e84f16ad7 100644
--- a/CRM/Contact/Import/Parser/Contact.php
+++ b/CRM/Contact/Import/Parser/Contact.php
@@ -2051,7 +2051,9 @@ class CRM_Contact_Import_Parser_Contact extends CRM_Import_Parser {
   /**
    * Run import.
    *
-   * @param array $mapper
+   * @param array $mapper Mapping as entered on MapField form.
+   *   e.g [['first_name']['email', 1]].
+   *   {@see \CRM_Contact_Import_Parser_Contact::getMappingFieldFromMapperInput}
    * @param int $mode
    * @param int $statusID
    *
@@ -2648,6 +2650,13 @@ class CRM_Contact_Import_Parser_Contact extends CRM_Import_Parser {
    * 1]
    *
    * @param array $fieldMapping
+   *   Field as submitted on the MapField form - this is a non-associative array,
+   *   the keys of which depend on the data/ field. Generally it will be one of
+   *   [$fieldName],
+   *   [$fieldName, $locationTypeID, $phoneTypeIDOrIMProviderIDIfRelevant],
+   *   [$fieldName, $websiteTypeID],
+   *   If the mapping is for a related contact it will be as above but the first
+   *   key will be the relationship key - eg. 5_a_b.
    * @param int $mappingID
    * @param int $columnNumber
    *
diff --git a/tests/phpunit/CRM/Contact/Import/Form/MapFieldTest.php b/tests/phpunit/CRM/Contact/Import/Form/MapFieldTest.php
index 4f54fb5b78..6e18707727 100644
--- a/tests/phpunit/CRM/Contact/Import/Form/MapFieldTest.php
+++ b/tests/phpunit/CRM/Contact/Import/Form/MapFieldTest.php
@@ -51,7 +51,9 @@ class CRM_Contact_Import_Form_MapFieldTest extends CiviUnitTestCase {
    * @dataProvider getSubmitData
    *
    * @param array $params
-   * @param array $mapper
+   * @param array $mapper Mapping as entered on MapField form.
+   *   e.g [['first_name']['email', 1]].
+   *   {@see \CRM_Contact_Import_Parser_Contact::getMappingFieldFromMapperInput}
    * @param array $expecteds
    *
    * @throws \API_Exception
diff --git a/tests/phpunit/CRM/Contact/Import/Parser/ContactTest.php b/tests/phpunit/CRM/Contact/Import/Parser/ContactTest.php
index c0dae22d37..0a63c0a6df 100644
--- a/tests/phpunit/CRM/Contact/Import/Parser/ContactTest.php
+++ b/tests/phpunit/CRM/Contact/Import/Parser/ContactTest.php
@@ -870,10 +870,13 @@ class CRM_Contact_Import_Parser_ContactTest extends CiviUnitTestCase {
    * @dataProvider validateDataProvider
    *
    * @param string $csv
-   * @param array $mapper
+   * @param array $mapper Mapping as entered on MapField form.
+   *   e.g [['first_name']['email', 1]].
+   *   {@see \CRM_Contact_Import_Parser_Contact::getMappingFieldFromMapperInput}
    * @param string $expectedError
    * @param array $submittedValues
    *
+   *
    * @throws \API_Exception
    */
   public function testValidation(string $csv, array $mapper, string $expectedError = '', $submittedValues = []): void {
@@ -1300,7 +1303,9 @@ class CRM_Contact_Import_Parser_ContactTest extends CiviUnitTestCase {
 
   /**
    * @param string $csv
-   * @param array $mapper
+   * @param array $mapper Mapping as entered on MapField form.
+   *   e.g [['first_name']['email', 1]].
+   *   {@see \CRM_Contact_Import_Parser_Contact::getMappingFieldFromMapperInput}
    * @param array $submittedValues
    *
    * @return array
@@ -1505,6 +1510,7 @@ class CRM_Contact_Import_Parser_ContactTest extends CiviUnitTestCase {
    * @param string $csv Name of csv file.
    * @param array $mapper Mapping as entered on MapField form.
    *   e.g [['first_name']['email', 1]].
+   *   {@see \CRM_Contact_Import_Parser_Contact::getMappingFieldFromMapperInput}
    * @param array $submittedValues
    *   Any submitted values overrides.
    *
@@ -1524,6 +1530,7 @@ class CRM_Contact_Import_Parser_ContactTest extends CiviUnitTestCase {
    * @param string $csv Name of csv file.
    * @param array $mapper Mapping as entered on MapField form.
    *   e.g [['first_name']['email', 1]].
+   *   {@see \CRM_Contact_Import_Parser_Contact::getMappingFieldFromMapperInput}
    * @param array $submittedValues
    */
   protected function importCSV(string $csv, array $mapper, array $submittedValues = []): void {
@@ -1556,7 +1563,8 @@ class CRM_Contact_Import_Parser_ContactTest extends CiviUnitTestCase {
 
   /**
    * @param string $csv
-   * @param array $mapper
+   * @param array $mapper Mapping as entered on MapField form.
+   *   e.g [['first_name']['email', 1]].
    * @param string $field
    * @param array $submittedValues
    *   Values submitted in the form process.
-- 
2.25.1