From 574b546c9c0461b9ba557eaacbac4013a3c53d7e Mon Sep 17 00:00:00 2001
From: Shibo Lyu <github@of.sb>
Date: Mon, 24 Jul 2023 11:42:56 +0800
Subject: [PATCH] doc: Basic documentation.

---
 Sources/CropImage/CropImageView.swift         | 43 +++++++++++++++----
 .../Documentation.docc/Documentation.md       | 21 +++++++++
 Sources/CropImage/PlatformImage.swift         |  6 +++
 3 files changed, 61 insertions(+), 9 deletions(-)
 create mode 100644 Sources/CropImage/Documentation.docc/Documentation.md

diff --git a/Sources/CropImage/CropImageView.swift b/Sources/CropImage/CropImageView.swift
index 3bb9ca6..8c603c8 100644
--- a/Sources/CropImage/CropImageView.swift
+++ b/Sources/CropImage/CropImageView.swift
@@ -10,15 +10,36 @@ import SwiftUI
 import UIKit
 #endif
 
+/// A view that allows the user to crop an image.
 public struct CropImageView: View {
-    public enum RenderError: Error {
+    /// Errors that could happen during the cropping process.
+    public enum CropError: Error {
+        /// SwiftUI `ImageRenderer` returned nil when calling `nsImage` or `uiImage`.
+        ///
+        /// See [SwiftUI - ImageRenderer](https://developer.apple.com/documentation/swiftui/imagerenderer) for more information.
         case imageRendererReturnedNil
+        /// `UIGraphicsGetCurrentContext()` call returned `nil`.
+        ///
+        /// It shouldn't happen, but if it does it will only be on iOS versions prior to 16.0.
+        case failedToGetCurrentUIGraphicsContext
+        /// `UIGraphicsGetImageFromCurrentImageContext()` call returned `nil`.
+        ///
+        /// It shouldn't happen, but if it does it will only be on iOS versions prior to 16.0.
+        case failedToGetImageFromCurrentUIGraphicsImageContext
     }
 
-    var image: PlatformImage
-    var targetSize: CGSize
-    var targetScale: CGFloat = 1
-    var onCrop: (Result<PlatformImage, Error>) -> Void
+    /// The image to crop.
+    public var image: PlatformImage
+    /// The intended size of the cropped image, in points.
+    public var targetSize: CGSize
+    /// The intended scale of the cropped image.
+    ///
+    /// This defines the point to pixel ratio for the output image. Defaults to `1`.
+    public var targetScale: CGFloat = 1
+    /// A closure that will be called when the user finishes cropping.
+    ///
+    /// The error should be a ``CropError``.
+    public var onCrop: (Result<PlatformImage, Error>) -> Void
 
     @State private var offset: CGSize = .zero
     @State private var scale: CGFloat = 1
@@ -34,13 +55,13 @@ public struct CropImageView: View {
             if let image = renderer.uiImage {
                 return image
             } else {
-                throw RenderError.imageRendererReturnedNil
+                throw CropError.imageRendererReturnedNil
             }
 #elseif os(macOS)
             if let image = renderer.nsImage {
                 return image
             } else {
-                throw RenderError.imageRendererReturnedNil
+                throw CropError.imageRendererReturnedNil
             }
 #endif
         } else {
@@ -53,9 +74,13 @@ public struct CropImageView: View {
             window.addSubview(hosting.view)
             window.makeKeyAndVisible()
             UIGraphicsBeginImageContextWithOptions(hosting.view.bounds.size, false, targetScale)
-            let context = UIGraphicsGetCurrentContext()!
+            guard let context = UIGraphicsGetCurrentContext() else {
+                throw CropError.failedToGetCurrentUIGraphicsContext
+            }
             hosting.view.layer.render(in: context)
-            let image = UIGraphicsGetImageFromCurrentImageContext()!
+            guard let image = UIGraphicsGetImageFromCurrentImageContext() else {
+                throw CropError.failedToGetImageFromCurrentUIGraphicsImageContext
+            }
             UIGraphicsEndImageContext()
             return image
 #endif
diff --git a/Sources/CropImage/Documentation.docc/Documentation.md b/Sources/CropImage/Documentation.docc/Documentation.md
new file mode 100644
index 0000000..a2605a2
--- /dev/null
+++ b/Sources/CropImage/Documentation.docc/Documentation.md
@@ -0,0 +1,21 @@
+# ``CropImageView``
+
+A simple SwiftUI view where user can move and resize an image to a pre-defined size.
+
+Supports iOS 14.0 and above, or macOS Ventura 13.0 and above.
+
+## Overview
+
+- Supports both iOS and macOS
+- Use `ImageRenderer` to render the cropped image, when possible
+- Very lightweight
+
+## Topics
+
+### Views
+
+- ``CropImageView``
+
+### Supporting Types
+
+- ``PlatformImage``
diff --git a/Sources/CropImage/PlatformImage.swift b/Sources/CropImage/PlatformImage.swift
index d815963..617ea5f 100644
--- a/Sources/CropImage/PlatformImage.swift
+++ b/Sources/CropImage/PlatformImage.swift
@@ -9,8 +9,14 @@ import Foundation
 
 #if os(macOS)
 import AppKit
+/// The image object type, aliased to each platform.
+///
+/// On macOS, it's `NSImage` and on iOS it's `UIImage`.
 public typealias PlatformImage = NSImage
 #elseif os(iOS)
 import UIKit
+/// The image object type, aliased to each platform.
+///
+/// On macOS, it's `NSImage` and on iOS it's `UIImage`.
 public typealias PlatformImage = UIImage
 #endif