documentation

Sources/LCEssentials/ImagePicker/ImagePickerController.swift

@@ -1,4 +1,4 @@
-//  
+//
 // Copyright (c) 2023 Loverde Co.
 //
 // Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -25,17 +25,29 @@ import UIKit
 import AVFoundation
 import Photos
 
+/// A protocol that defines the methods an image picker delegate should implement.
 public protocol ImagePickerControllerDelegate: AnyObject {
+    /// Tells the delegate that an image has been selected by the image picker.
+    /// - Parameter image: The `UIImage` that was selected, or `nil` if the selection was canceled or failed.
     func imagePicker(didSelect image: UIImage?)
 }
 
+/// A custom `UIViewController` that provides functionality for picking images from the camera or photo library.
+///
+/// This controller handles permissions for camera and photo library access and presents
+/// a `UIImagePickerController` to the user.
 public class ImagePickerController: UIViewController, UINavigationControllerDelegate {
     
     private var isAlertOpen: Bool = false
     private var imagePickerController: UIImagePickerController = UIImagePickerController()
+    
+    /// The delegate for the `ImagePickerController`, which will receive callbacks when an image is selected.
     public weak var delegate: ImagePickerControllerDelegate?
+    
+    /// A boolean value that determines whether the user can edit the selected image. Defaults to `false`.
     public var isEditable: Bool = false
 
+    /// Initializes a new `ImagePickerController` instance.
     public init() {
         super.init(nibName: nil, bundle: nil)
     }
@@ -52,7 +64,10 @@ public class ImagePickerController: UIViewController, UINavigationControllerDele
         self.imagePickerController.mediaTypes = ["public.image", "public.movie"]
     }
 
-    
+    /// Presents the image picker to the user.
+    ///
+    /// This method checks for camera and photo library permissions and then presents an alert
+    /// allowing the user to choose between the camera or photo roll, or to grant permissions if needed.
     public func openImagePicker(){
         var cameraPerm: Bool = false
         var albumPerm: Bool = false
@@ -85,6 +100,10 @@ public class ImagePickerController: UIViewController, UINavigationControllerDele
     }
     
     
+    /// Presents an `UIAlertController` with options to open the camera, photo roll, or grant permissions.
+    /// - Parameters:
+    ///   - forCamera: A boolean indicating whether camera access is granted. Defaults to `true`.
+    ///   - forAlbum: A boolean indicating whether photo album access is granted. Defaults to `true`.
     private func openAlerts(forCamera:Bool = true, forAlbum:Bool = true){
         let alert = UIAlertController(title: "Choose an option", message: nil, preferredStyle: .actionSheet)
         if forCamera {
@@ -117,6 +136,9 @@ public class ImagePickerController: UIViewController, UINavigationControllerDele
         }
     }
     
+    /// Opens the camera device using `UIImagePickerController`.
+    ///
+    /// If the camera is not available, an alert message is presented to the user.
     private func openCameraDevice(){
         if(UIImagePickerController.isSourceTypeAvailable(UIImagePickerController.SourceType.camera)){
             self.imagePickerController.sourceType = UIImagePickerController.SourceType.camera
@@ -130,12 +152,14 @@ public class ImagePickerController: UIViewController, UINavigationControllerDele
         }
     }
     
+    /// Opens the photo library using `UIImagePickerController`.
     private func openAlbumDevice(){
         self.imagePickerController.sourceType = UIImagePickerController.SourceType.photoLibrary
         self.modalPresentationStyle = .fullScreen
         self.present(self.imagePickerController, animated: true, completion: nil)
     }
     
+    /// Requests photo library access and if denied, guides the user to app settings.
     private func openAppSettingsPhoto(){
         PHPhotoLibrary.requestAuthorization({status in
             if status == .authorized{
@@ -160,6 +184,7 @@ public class ImagePickerController: UIViewController, UINavigationControllerDele
         })
     }
     
+    /// Requests camera access and if denied, guides the user to app settings.
     private func openAppSettingsCamera(){
         AVCaptureDevice.requestAccess(for: AVMediaType.video, completionHandler: { (granted: Bool) -> Void in
             if granted == true {
@@ -189,6 +214,8 @@ public class ImagePickerController: UIViewController, UINavigationControllerDele
 
 extension ImagePickerController: UIImagePickerControllerDelegate {
     
+    /// Tells the delegate that the user canceled the pick operation.
+    /// - Parameter picker: The image picker controller.
     @objc public func imagePickerControllerDidCancel(_ picker: UIImagePickerController) {
         self.delegate?.imagePicker(didSelect: nil)
         picker.dismiss(animated: true, completion: {
@@ -196,6 +223,10 @@ extension ImagePickerController: UIImagePickerControllerDelegate {
         })
     }
     
+    /// Tells the delegate that the user picked an image or movie.
+    /// - Parameters:
+    ///   - picker: The image picker controller.
+    ///   - info: A dictionary containing the original image, and possibly an edited image or a movie URL.
     @objc public func imagePickerController(_ picker: UIImagePickerController,
                                             didFinishPickingMediaWithInfo info: [UIImagePickerController.InfoKey: Any]) {
         if let image = info[UIImagePickerController.InfoKey.editedImage] as? UIImage {