Documenting code

CHANGELOG.md

@@ -12,8 +12,9 @@ N/A
 
 #### Enhancements
 
+- Completing missing unit tests
+- Adding documentation to the code
 - Adding `UIElementPreview`, an easy way to generate mulitple SwiftUI previews with different configuration
-- Completing missing unit tests 
 - BundleExtension:
 
 ```swift

Sources/Extensions/AppKit/NSView/NSViewExtension.swift

@@ -11,6 +11,7 @@ import Cocoa
 
 extension NSView {
 
+    /// Automatically translate all the subviews using their text as localizable's key.
     @objc
     public func convertLocalizables() {
         if subviews.isEmpty {
@@ -38,21 +39,26 @@ extension NSView {
 // MARK: - Frame
 
 extension NSView {
+
+    /// Get or set the NSView's frame `x` value.
     public var x: CGFloat {
         get { frame.x }
         set { frame = frame.with(x: newValue) }
     }
 
+    /// Get or set the NSView's frame `y` value.
     public var y: CGFloat {
         get { frame.y }
         set { frame = frame.with(y: newValue) }
     }
 
+    /// Get or set the NSView's frame `width` value.
     public var width: CGFloat {
         get { frame.width }
         set { frame = frame.with(width: newValue) }
     }
 
+    /// Get or set the NSView's frame `height` value.
     public var height: CGFloat {
         get { frame.height }
         set { frame = frame.with(height: newValue) }

Sources/Extensions/CoreGraphics/CGFloatLiteral/CGFloatLiteral.swift

@@ -8,7 +8,8 @@ import CoreGraphics
 
 extension IntegerLiteralType {
 
-    // swiftlint:disable:next identifier_name
+    // swiftlint:disable identifier_name
+    /// Map an `IntegerLiteralType` to a `CGFloat`
     public var f: CGFloat {
         CGFloat(self)
     }
@@ -17,7 +18,7 @@ extension IntegerLiteralType {
 
 extension FloatLiteralType {
 
-    // swiftlint:disable:next identifier_name
+    /// Map an `FloatLiteralType` to a `CGFloat`
     public var f: CGFloat {
         CGFloat(self)
     }

Sources/Extensions/CoreGraphics/CGPoint/CGPointExtension.swift

@@ -9,14 +9,29 @@ import CoreGraphics
 
 extension CGPoint {
 
+    /// Create a new `CGPoint` by adding up two `CGPoint` together.
+    /// - Parameters:
+    ///   - lhs: One of the two `CGPoint` that will be added up.
+    ///   - rhs: One of the two `CGPoint` that will be added up.
+    /// - Returns: The `CGPoint` resulting of the two others addition.
     public static func + (lhs: CGPoint, rhs: CGPoint) -> CGPoint {
         CGPoint(x: lhs.x + rhs.x, y: lhs.y + rhs.y)
     }
 
+    /// Create a new `CGPoint` by substracting two `CGPoint` together.
+    /// - Parameters:
+    ///   - lhs: One of the two `CGPoint` that will be substracted.
+    ///   - rhs: One of the two `CGPoint` that will be substracted.
+    /// - Returns: The `CGPoint` resulting of the two others substraction.
     public static func - (lhs: CGPoint, rhs: CGPoint) -> CGPoint {
         CGPoint(x: lhs.x - rhs.x, y: lhs.y - rhs.y)
     }
 
+    /// Create a new `CGPoint` by multipliing a `CGPoint` with a scalar.
+    /// - Parameters:
+    ///   - point: The `CGPoint` that will be multiplied.
+    ///   - scalar: The scalar that will be used to multiply the CGPoint.
+    /// - Returns: The result of the multiplication between the CGPoint and the scalar.
     public static func * (point: CGPoint, scalar: CGFloat) -> CGPoint {
         CGPoint(x: point.x * scalar, y: point.y * scalar)
     }

Sources/Extensions/CoreGraphics/CGRect/CGRectExtensions.swift

@@ -9,40 +9,60 @@ import CoreGraphics
 
 extension CGRect {
 
+    /// Returns the `x` value of the CGRect.
     public var x: CGFloat {
         origin.x
     }
 
+    /// Returns the `y` value of the CGRect.
     public var y: CGFloat {
         origin.y
     }
 
-    public func with(x: CGFloat) -> CGRect {
-        CGRect(x: x, y: y, width: width, height: height)
-    }
-
 }
 
 // MARK: - Transform
 
 extension CGRect {
 
+    /// Replace the current CGRect's `x` value with a new one.
+    /// - Parameter x: The new `x` value.
+    /// - Returns: The `CGRect` containing the new `x` value.
+    public func with(x: CGFloat) -> CGRect {
+        CGRect(x: x, y: y, width: width, height: height)
+    }
+
+    /// Replace the current CGRect's `y` value with a new one.
+    /// - Parameter y: The new `y` value.
+    /// - Returns: The `CGRect` containing the new `y` value.
     public func with(y: CGFloat) -> CGRect {
         CGRect(x: x, y: y, width: width, height: height)
     }
 
+    /// Replace the current CGRect's `width` value with a new one.
+    /// - Parameter width: The new `width` value.
+    /// - Returns: The `CGRect` containing the new `width` value.
     public func with(width: CGFloat) -> CGRect {
         CGRect(x: x, y: y, width: width, height: height)
     }
 
+    /// Replace the current CGRect's `height` value with a new one.
+    /// - Parameter height: The new `height` value.
+    /// - Returns: The `CGRect` containing the new `height` value.
     public func with(height: CGFloat) -> CGRect {
         CGRect(x: x, y: y, width: width, height: height)
     }
 
+    /// Replace the current CGRect's `origin` value with a new one.
+    /// - Parameter origin: The new `origin` value.
+    /// - Returns: The `CGRect` containing the new `origin` value.
     public func with(origin: CGPoint) -> CGRect {
         CGRect(origin: origin, size: size)
     }
 
+    /// Replace the current CGRect's `size` value with a new one.
+    /// - Parameter size: The new `size` value.
+    /// - Returns: The `CGRect` containing the new `size` value.
     public func with(size: CGSize) -> CGRect {
         CGRect(origin: origin, size: size)
     }

Sources/Extensions/Foundation/Bundle/BundleExtension.swift

@@ -9,22 +9,32 @@ import Foundation
 
 extension Bundle {
 
+    /// The app name extracted from the `infoDictionary`.
+    /// - Returns: String.
     public var appName: String {
         string(for: kCFBundleNameKey as String)
     }
 
+    /// The app version extracted from the `infoDictionary`.
+    /// - Returns: String.
     @objc public var appVersion: String {
         string(for: "CFBundleShortVersionString")
     }
 
+    /// The display name extracted from the `infoDictionary`.
+    /// - Returns: String.
     public var displayName: String {
         string(for: "CFBundleDisplayName")
     }
 
+    /// The app build extracted from the `infoDictionary`.
+    /// - Returns: String.
     public var appBuild: String {
         string(for: kCFBundleVersionKey as String)
     }
 
+    /// The app bundle identifier extracted from the `infoDictionary`.
+    /// - Returns: String.
     public var bundleId: String {
         string(for: "CFBundleIdentifier")
     }
@@ -35,6 +45,8 @@ extension Bundle {
 
 extension Bundle {
 
+    /// Check either the app has been installed using TestFlight.
+    /// - Returns: Bool.
     public var isInTestFlight: Bool {
         appStoreReceiptURL?.path.contains("sandboxReceipt") == true
     }
@@ -65,7 +77,7 @@ extension Bundle {
 
 extension Bundle {
 
-    func string(for key: String) -> String {
+    private func string(for key: String) -> String {
         guard let infoDictionary = Bundle.main.infoDictionary,
             let value = infoDictionary[key] as? String else {
                 return ""

Sources/Extensions/Foundation/Color/ColorExtension.swift

@@ -13,6 +13,8 @@
 
 extension SwiftyColor {
 
+    /// Initialize a Color from an hex String.
+    /// - Parameter hex: the hex used to create the color.
     @objc
     public convenience init(hex: String) {
         let hex = hex.trimmingCharacters(in: NSCharacterSet.alphanumerics.inverted)
@@ -42,24 +44,32 @@ extension SwiftyColor {
 #if !os(OSX)
 extension SwiftyColor {
 
+    /// Extract the red component from the `Color`.
+    /// - Returns: Int.
     public var redComponent: Int {
         var red: CGFloat = 0
         getRed(&red, green: nil, blue: nil, alpha: nil)
         return Int(red * 255)
     }
 
+    /// Extract the green component from the `Color`.
+    /// - Returns: Int.
     public var greenComponent: Int {
         var green: CGFloat = 0
         getRed(nil, green: &green, blue: nil, alpha: nil)
         return Int(green * 255)
     }
 
+    /// Extract the blue component from the `Color`.
+    /// - Returns: Int.
     public var blueComponent: Int {
         var blue: CGFloat = 0
         getRed(nil, green: nil, blue: &blue, alpha: nil)
         return Int(blue * 255)
     }
 
+    /// Extract the alpha component from the `Color`.
+    /// - Returns: Int.
     public var alpha: CGFloat {
         var alpha: CGFloat = 0
         getRed(nil, green: nil, blue: nil, alpha: &alpha)
@@ -73,10 +83,16 @@ extension SwiftyColor {
 
 extension SwiftyColor {
 
+    /// Make the Color lighter.
+    /// - Parameter amount: the amount of brightness to apply/
+    /// - Returns: The `Color` with the amount lighter applied.
     public func lighter(amount: CGFloat = 0.25) -> SwiftyColor {
         hueColor(withBrightnessAmount: 1 + amount)
     }
 
+    /// Make the Color darker.
+    /// - Parameter amount: the amount of dark to apply.
+    /// - Returns: The `Color` with the amount darker applied.
     public func darker(amount: CGFloat = 0.25) -> SwiftyColor {
         hueColor(withBrightnessAmount: 1 - amount)
     }

Sources/Extensions/Foundation/Date/DateExtension.swift

@@ -9,6 +9,12 @@ import Foundation
 
 extension Date {
 
+    /// Initialize a Date from a String and a specified format.
+    /// - Parameters:
+    ///   - string: The string to map.
+    ///   - format: The format which will be used to create the `Date`.
+    /// - Returns: If sucessfull, the `Date` created from the `string` and format,
+    ///            otherwise `nil` meaning that's the `string` didn't match the `format`.
     public init?(fromString string: String, format: String) {
         let formatter = SUDateFormatter.shared
         formatter.dateFormat = format
@@ -24,13 +30,23 @@ extension Date {
 
 extension Date {
 
+    /// Create a String from a Date.
+    /// - Parameters:
+    ///   - dateStyle: the date style that will be applied when creating the string. Default is `medium`.
+    ///   - timeStyle: the time style that will be applied when creating the string. Default is `medium`.
+    /// - Returns: the string created from the `Date` and formatted using the `dateStyle` and `timeStyle`.
     public func string(dateStyle: DateFormatter.Style = .medium, timeStyle: DateFormatter.Style = .medium) -> String {
         let formatter = SUDateFormatter.shared
         formatter.dateStyle = dateStyle
         formatter.timeStyle = timeStyle
         return formatter.string(from: self as Date)
     }
 
+    /// Create a String from a Date.
+    /// - Parameter format: the date format that will be applied when creating the string.
+    ///                     Note that the format must be a valid date format, you can find example here:
+    ///                      https://www.nsdateformatter.com.
+    /// - Returns: the string created from the `Date` and formatted using the `format`.
     public func string(format: String) -> String {
         let formatter = SUDateFormatter.shared
         formatter.dateFormat = format
@@ -43,24 +59,36 @@ extension Date {
 
 extension Date {
 
+    /// Calculate the number of days since another `Date`.
+    /// - Parameter date: the date that will be used for to calculate the number of days.
+    /// - Returns: the number of days since the dedicated dates.
     public func days(since date: Date) -> Double {
         var diff = self.timeIntervalSinceNow - date.timeIntervalSinceNow
         diff = fabs(diff / 86_400)
         return diff
     }
 
+    /// Calculate the number of hours since another `Date`.
+    /// - Parameter date: the date that will be used for to calculate the number of hours.
+    /// - Returns: the number of hours since the dedicated dates.
     public func hours(since date: Date) -> Double {
         var diff = self.timeIntervalSinceNow - date.timeIntervalSinceNow
         diff = fabs(diff / 3600)
         return diff
     }
 
+    /// Calculate the number of minutes since another `Date`.
+    /// - Parameter date: the date that will be used for to calculate the number of minutes.
+    /// - Returns: the number of minutes since the dedicated dates.
     public func minutes(since date: Date) -> Double {
         var diff = self.timeIntervalSinceNow - date.timeIntervalSinceNow
         diff = fabs(diff / 60)
         return diff
     }
 
+    /// Calculate the number of seconds since another `Date`.
+    /// - Parameter date: the date that will be used for to calculate the number of seconds.
+    /// - Returns: the number of seconds since the dedicated dates.
     public func seconds(since date: Date) -> Double {
         var diff = self.timeIntervalSinceNow - date.timeIntervalSinceNow
         diff = fabs(diff)
@@ -73,10 +101,14 @@ extension Date {
 
 extension Date {
 
+    /// Check if a `Date` is in the future.
+    /// - Returns: Bool.
     public var isInFuture: Bool {
         self > Date()
     }
 
+    /// Check if a `Date` is in the past.
+    /// - Returns: Bool.
     public var isInPast: Bool {
         self < Date()
     }