Improve comment blocks for mapper

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
    *

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

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.