ios: rename method finalizePHPickerImage: and document it (#947)

- Rename to `processPHPickerImage:` since it does rotating, scaling and cropping and prepare the metadata
- Document the method and code

src/ios/CDVCamera.h

@@ -137,7 +137,7 @@ typedef NSUInteger CDVMediaType;
 // PHPickerViewController specific methods (iOS 14+)
 #if __IPHONE_OS_VERSION_MAX_ALLOWED >= 140000 // Always true on XCode12+
 - (void)showPHPicker:(NSString*)callbackId withOptions:(CDVPictureOptions*)pictureOptions API_AVAILABLE(ios(14));
-- (void)finalizePHPickerImage:(UIImage*)image metadata:(NSDictionary*)metadata callbackId:(NSString*)callbackId options:(CDVPictureOptions*)options API_AVAILABLE(ios(14));
+- (void)processPHPickerImage:(UIImage*)image metadata:(NSDictionary*)metadata callbackId:(NSString*)callbackId options:(CDVPictureOptions*)options API_AVAILABLE(ios(14));
 // PHPickerViewControllerDelegate method
 - (void)picker:(PHPickerViewController *)picker didFinishPicking:(NSArray<PHPickerResult *> *)results API_AVAILABLE(ios(14));
 #endif

src/ios/CDVCamera.m

@@ -413,7 +413,7 @@ static NSString* MIME_JPEG    = @"image/jpeg";
                     return;
                 }
                 
-                [weakSelf finalizePHPickerImage:[UIImage imageWithData:imageData]
+                [weakSelf processPHPickerImage:[UIImage imageWithData:imageData]
                                        metadata:[weakSelf convertImageMetadata:imageData]
                                      callbackId:callbackId
                                         options:pictureOptions];
@@ -422,12 +422,18 @@ static NSString* MIME_JPEG    = @"image/jpeg";
     }];
 }
 
-- (void)finalizePHPickerImage:(UIImage*)image
+/**
+    Processes an image obtained from PHPickerViewController according to specified pictureOptions,
+    after it returns the CDVPluginResult.
+    The processing of the image is similar what retrieveImage: and processImage: is doing for UIImagePickerController.
+*/
+- (void)processPHPickerImage:(UIImage*)image
                      metadata:(NSDictionary*)metadata
                    callbackId:(NSString*)callbackId
                       options:(CDVPictureOptions*)options API_AVAILABLE(ios(14))
 {
     // Process image according to options
+    // The same is done in retrieveImage:
     UIImage *processedImage = image;
     
     if (options.correctOrientation) {
@@ -446,7 +452,8 @@ static NSString* MIME_JPEG    = @"image/jpeg";
         }
     }
 
-    // Store metadata, which will be processed in resultForImage
+    // Prepare self.metadata, which replicates the logic from processImage: for the UIImagePickerController
+    // self.metadata which will be set to the image in resultForImage:
     if (metadata.count > 0) {
         self.metadata = [NSMutableDictionary dictionary];
 
@@ -471,9 +478,11 @@ static NSString* MIME_JPEG    = @"image/jpeg";
     __weak CDVCamera* weakSelf = self;
     
     // Create info dictionary similar to UIImagePickerController
+    // Will be used in retrieveImage: to get the image and do processing like here was done
     NSMutableDictionary *info = [@{ UIImagePickerControllerOriginalImage : processedImage } mutableCopy];
     
     if (metadata.count > 0) {
+        // This is not used anywhere and can be removed
         info[UIImagePickerControllerMediaMetadata] = metadata;
     }
     

tests/ios/CDVCameraTest/CDVCameraLibTests/CameraTest.m

@@ -563,9 +563,9 @@
     SEL processSelector = @selector(processPHPickerImage:assetIdentifier:callbackId:options:);
     XCTAssertTrue([self.plugin respondsToSelector:processSelector]);
     
-    // Test that finalizePHPickerImage method exists
+    // Test that processPHPickerImage method exists
-    SEL finalizeSelector = @selector(finalizePHPickerImage:metadata:callbackId:options:);
+    SEL processPHPickerImageSelector = @selector(processPHPickerImage:metadata:callbackId:options:);
-    XCTAssertTrue([self.plugin respondsToSelector:finalizeSelector]);
+    XCTAssertTrue([self.plugin respondsToSelector:processPHPickerImageSelector]);
 }
 #endif