doc: update for missing parts

Author: EyreFree

Source/Styles/EFQRCodeStyle.swift

@@ -196,6 +196,16 @@ public class EFStyleParamIcon {
         )
     }
 
+    /**
+     * Generates SVG elements for rendering the icon in the QR code.
+     *
+     * This method creates the necessary SVG markup to display the icon at the center
+     * of the QR code with proper masking, scaling, and border styling.
+     *
+     * - Parameter qrcode: The QR code model containing module structure and dimensions.
+     * - Returns: An array of SVG strings representing the icon elements.
+     * - Throws: `EFQRCodeError` if color conversion or image processing fails.
+     */
     func write(qrcode: QRCode) throws -> [String] {
         struct Anchor {
             static var uniqueMark: Int = 0
@@ -327,6 +337,15 @@ public class EFStyleParamBackdrop {
         self.quietzone = quietzone
     }
 
+    /**
+     * Calculates the viewBox dimensions for the QR code with quiet zone considerations.
+     *
+     * This method determines the coordinate system and dimensions for the SVG viewBox,
+     * taking into account any specified quiet zone (border space) around the QR code.
+     *
+     * - Parameter moduleCount: The number of modules (squares) along one side of the QR code.
+     * - Returns: A CGRect defining the viewBox coordinates and dimensions.
+     */
     func viewBox(moduleCount: Int) -> CGRect {
         if let quietzone = quietzone {
             return CGRect(
@@ -339,6 +358,19 @@ public class EFStyleParamBackdrop {
         return CGRect(x: -1, y: -1, width: moduleCount.cgFloat + 2, height: moduleCount.cgFloat + 2)
     }
 
+    /**
+     * Generates the opening and closing SVG markup for the QR code backdrop.
+     *
+     * This method creates the SVG container structure with background styling,
+     * clipping paths, and coordinate transformations. It returns a tuple containing
+     * the opening SVG elements and the closing elements.
+     *
+     * - Parameters:
+     *   - qrcode: The QR code model containing structure information.
+     *   - viewBoxRect: The viewBox rectangle defining the coordinate system.
+     * - Returns: A tuple containing (opening SVG markup, closing SVG markup).
+     * - Throws: `EFQRCodeError` if color conversion or image processing fails.
+     */
     func generateSVG(qrcode: QRCode, viewBoxRect: CGRect) throws -> (String, String) {
         let bgColor: String = try color.hexString()
         let bgAlpha: CGFloat = max(0, try color.alpha())
@@ -390,6 +422,16 @@ public class EFStyleParamBackdropImage {
         self.mode = mode
     }
 
+    /**
+     * Generates SVG markup for the backdrop image.
+     *
+     * This method processes the backdrop image according to the specified scaling mode
+     * and generates the corresponding SVG image element with proper sizing and encoding.
+     *
+     * - Parameter size: The target size for the backdrop image in the SVG coordinate system.
+     * - Returns: An SVG image element string with base64-encoded image data.
+     * - Throws: `EFQRCodeError` if image processing or encoding fails.
+     */
     func write(size: CGSize) throws -> String {
         let imageCliped: CGImage = try self.mode.imageForContent(ofImage: image, inCanvasOfRatio: size)
         let pngBase64EncodedString: String = try imageCliped.pngBase64EncodedString()

Source/Styles/EFQRCodeStyleBasic.swift

@@ -295,8 +295,16 @@ public class EFQRCodeStyleBasic: EFQRCodeStyleBase {
     /// The parameters for the basic style.
     let params: EFStyleBasicParams
 
+    /// SVG path data for rounded square shapes used in QR code styling.
+    /// This path defines a rounded rectangle with corner radius optimized for QR code aesthetics.
     static let sq25: String = "M32.048565,-1.29480038e-15 L67.951435,1.29480038e-15 C79.0954192,-7.52316311e-16 83.1364972,1.16032014 87.2105713,3.3391588 C91.2846454,5.51799746 94.4820025,8.71535463 96.6608412,12.7894287 C98.8396799,16.8635028 100,20.9045808 100,32.048565 L100,67.951435 C100,79.0954192 98.8396799,83.1364972 96.6608412,87.2105713 C94.4820025,91.2846454 91.2846454,94.4820025 87.2105713,96.6608412 C83.1364972,98.8396799 79.0954192,100 67.951435,100 L32.048565,100 C20.9045808,100 16.8635028,98.8396799 12.7894287,96.6608412 C8.71535463,94.4820025 5.51799746,91.2846454 3.3391588,87.2105713 C1.16032014,83.1364972 5.01544207e-16,79.0954192 -8.63200256e-16,67.951435 L8.63200256e-16,32.048565 C-5.01544207e-16,20.9045808 1.16032014,16.8635028 3.3391588,12.7894287 C5.51799746,8.71535463 8.71535463,5.51799746 12.7894287,3.3391588 C16.8635028,1.16032014 20.9045808,7.52316311e-16 32.048565,-1.29480038e-15 Z"
+    
+    /// Horizontal offset values for planet-style position detection patterns.
+    /// These values define the x-axis positions of satellite elements relative to the center.
     static let planetsVw: [CGFloat] = [3, -3]
+    
+    /// Vertical offset values for planet-style position detection patterns.
+    /// These values define the y-axis positions of satellite elements relative to the center.
     static let planetsVh: [CGFloat] = [3, -3]
 
     /**

Source/Styles/EFQRCodeStyleResampleImage.swift

@@ -516,6 +516,23 @@ public class EFQRCodeStyleResampleImage: EFQRCodeStyleBase {
         return pointList
     }
 
+    /**
+     * Generates SVG markup for image-resampled QR code modules.
+     *
+     * This method creates the resample image effect by sampling colors from the source image
+     * and applying them to the QR code modules. It processes the image pixels and maps them
+     * to QR code module positions with proper contrast adjustments.
+     *
+     * - Parameters:
+     *   - params: The resample image styling parameters.
+     *   - qrcode: The QR code model containing module structure.
+     *   - image: The image parameters for resampling, or nil if no image is available.
+     *   - newWidth: The target width for the resampled image in pixels.
+     *   - newHeight: The target height for the resampled image in pixels.
+     *   - color: The fallback hex color string for modules when image sampling fails.
+     * - Returns: An SVG string containing the image-resampled QR code modules.
+     * - Throws: `EFQRCodeError` if image processing or color conversion fails.
+     */
     func writeResImage(params: EFStyleResampleImageParams, qrcode: QRCode, image: EFStyleResampleImageParamsImage?, newWidth: Int, newHeight: Int, color: String) throws -> String {
         guard let image = image else { return "" }
 
@@ -578,6 +595,17 @@ public class EFQRCodeStyleResampleImage: EFQRCodeStyleBase {
         + part2
     }
 
+    /**
+     * Generates custom SVG markup for non-data modules in the resample image QR code.
+     *
+     * This method creates SVG elements for alignment patterns, timing patterns, and
+     * position detection patterns that are not part of the main data resampling.
+     * These elements use traditional QR code styling rather than image sampling.
+     *
+     * - Parameter qrcode: The QR code model containing module structure and type information.
+     * - Returns: An SVG string containing the custom-styled QR code control patterns.
+     * - Throws: `EFQRCodeError` if color conversion fails.
+     */
     func customSVG(qrcode: QRCode) throws -> String {
         let alignType: EFStyleResampleImageParamAlignStyle = params.align.style
         let alignColor: String = try params.align.color.hexString()
@@ -663,17 +691,51 @@ public class EFQRCodeStyleResampleImage: EFQRCodeStyleBase {
     }
 }
 
+/**
+ * Extensions for CGImage to support resample image QR code generation.
+ *
+ * This extension provides utility methods for processing images used in
+ * resample image QR code styles, including color analysis and pixel sampling.
+ */
 extension CGImage {
 
-    // red, green, blue: [0, 255]
-    // alpha: [0, 1]
-    // return: [0, 255]
+    /**
+     * Calculates the grayscale value for RGBA color components with gamma correction.
+     *
+     * This method converts RGB color values to grayscale using standard luminance
+     * coefficients and applies alpha blending for proper color representation.
+     *
+     * - Parameters:
+     *   - red: The red component value (0-255).
+     *   - green: The green component value (0-255).
+     *   - blue: The blue component value (0-255).
+     *   - alpha: The alpha component value (0-1).
+     * - Returns: The calculated grayscale value (0-255).
+     */
     func gamma(_ red: CGFloat, _ green: CGFloat, _ blue: CGFloat, _ alpha: CGFloat) -> CGFloat {
         let gray: CGFloat = 0.2126 * red + 0.7152 * green + 0.0722 * blue
         let weightedGray: CGFloat = gray * alpha + (1 - alpha) * 255.0
         return weightedGray
     }
 
+    /**
+     * Generates QR code modules by sampling grayscale values from the image.
+     *
+     * This method processes the image to create QR code modules based on pixel brightness,
+     * applying contrast and exposure adjustments. It handles different QR code module types
+     * (data, alignment, timing) and creates appropriate SVG elements for each.
+     *
+     * - Parameters:
+     *   - params: The resample image styling parameters.
+     *   - qrcode: The QR code model containing module structure and type information.
+     *   - newWidth: The target width for image resampling.
+     *   - newHeight: The target height for image resampling.
+     *   - contrast: The contrast adjustment value. Defaults to 0.
+     *   - exposure: The exposure adjustment value. Defaults to 0.
+     *   - color: The fallback color string for modules when image sampling fails.
+     * - Returns: An array of SVG strings representing the QR code modules.
+     * - Throws: `EFQRCodeError` if color conversion or image processing fails.
+     */
     func getGrayPointList(params: EFStyleResampleImageParams, qrcode: QRCode, newWidth: Int, newHeight: Int, contrast: CGFloat = 0, exposure: CGFloat = 0, color: String) throws -> [String] {
         // filter trans area
         let nCount: Int = qrcode.model.moduleCount