add documentation to the methods

Author: mikhailChelbaev

Sources/AutoLayout/LayoutConstraints+Helpers.swift

@@ -1,17 +1,50 @@
 extension LayoutConstraints {
+  /// Merges multiple ``LayoutConstraints`` into a single ``LayoutConstraints``.
+  /// 
+  /// Might be useful when grouping constraints of the same view.
+  /// 
+  /// ```swift
+  /// let constraints = LayoutConstraints.merged {
+  ///   view.horizontally(16)
+  ///   view.centerVertically()
+  /// }
+  /// ```
+  /// 
+  /// > Note: If two or more elements have the same non-nil constraint, the result will contain the constraint from the latest element.
+  /// - Parameter constraints: Constraints that should be merged.
+  /// - Returns: An instance that contains constraints from the all provided ``LayoutConstraints``.
   public static func merged(@LayoutConstraintsBuilder _ constraints: () -> LayoutConstraints) -> LayoutConstraints {
     return constraints()
   }
 }
 
 extension LayoutConstraints {
+  /// Merges the provided ``LayoutConstraints`` with a current instance.
+  ///
+  /// > Note: If the current instance and the provided instance have the same non-nil constraint, the constraint in the current instance will be overridden with a constraint from the provided instance.
+  /// - Parameter constraint: ``LayoutConstraints`` that should be merged with the current instance.
   public mutating func merge(with constraint: LayoutConstraints) {
     self = LayoutConstraints.merged {
       self
       constraint
     }
   }
-
+  
+  /// Merges the provided constraints with a current instance.
+  ///
+  /// Might be useful when grouping existing constraints with new values.
+  ///
+  /// ```swift
+  /// var constraints = view.leading(10)
+  /// ...
+  /// constraints.merge(with: {
+  ///   view.top(10)
+  ///   view.bottom(20)
+  /// })
+  /// ```
+  ///
+  /// > Note: If two or more elements have the same non-nil constraint, the current instance will contain the constraint from the latest element.
+  /// - Parameter constraints: Constraints that should be merged with the current instance.
   public mutating func merge(@LayoutConstraintsBuilder with constraints: () -> LayoutConstraints) {
     self = LayoutConstraints.merged {
       self

Sources/AutoLayout/LayoutConstraints.swift

@@ -1,25 +1,35 @@
 import UIKit
 
-/// Contains constraints of the view.
+/// A structure that holds references to various layout constraints applied to a view.
+///
+/// The `LayoutConstraints` struct is used to store the constraints created by layout helper methods. Each property corresponds to a specific type of constraint that has been applied.
+///
+/// This struct allows you to easily access and manipulate specific constraints after they have been applied to a view, facilitating adjustments or deactivations as needed.
+///
+/// ```swift
+/// let constraints = myView.edges(16)
+/// constraints.top?.constant = 20  // Adjust the top constraint's constant
+/// constraints.trailing?.isActive = false  // Deactivate the trailing constraint
+/// ```
 public struct LayoutConstraints {
-  /// Top constraint.
+  /// The top edge constraint.
   public var top: NSLayoutConstraint?
-  /// Leading constraint.
+  /// The leading edge constraint.
   public var leading: NSLayoutConstraint?
-  /// Bottom constraint.
+  /// The bottom edge constraint.
   public var bottom: NSLayoutConstraint?
-  /// Trailing constraint.
+  /// The trailing edge constraint.
   public var trailing: NSLayoutConstraint?
-  /// Vertical constraint.
+  /// The vertical alignment constraint (e.g., center Y).
   public var vertical: NSLayoutConstraint?
-  /// Horizontal constraint.
+  /// The horizontal alignment constraint (e.g., center X).
   public var horizontal: NSLayoutConstraint?
-  /// Width constraint.
+  /// The width constraint.
   public var width: NSLayoutConstraint?
-  /// Height constraint.
+  /// The height constraint.
   public var height: NSLayoutConstraint?
 
-  /// Array of all constraints.
+  /// Array with all constraints.
   public var allConstraints: [NSLayoutConstraint?] {
     return [
       self.top,
@@ -54,12 +64,12 @@ public struct LayoutConstraints {
     self.height = height
   }
 
-  /// Activates existing constraints.
+  /// Activates all existing constraints.
   public func activateAll() {
     self.allConstraints.forEach { $0?.isActive = true }
   }
 
-  /// Deactivates existing constraints.
+  /// Deactivates all existing constraints.
   public func deactivateAll() {
     self.allConstraints.forEach { $0?.isActive = false }
   }

Sources/AutoLayout/LayoutConstraintsBuilder.swift

@@ -1,3 +1,6 @@
+/// A result builder for merging multiple ``LayoutConstraints`` into a single ``LayoutConstraints``.
+///
+/// NOTE: If two elements have the same non-nil constraint, the result will contain the constraint of the latest element.
 @resultBuilder
 public struct LayoutConstraintsBuilder {
   public static func buildBlock(_ constraints: LayoutConstraints...) -> LayoutConstraints {

Sources/AutoLayout/UIView+Layout.swift

@@ -1,6 +1,14 @@
 import UIKit
 
 extension UIView {
+  /// Constrains the view's leading anchor to the leading anchor of another view or its superview.
+  ///
+  /// - Parameters:
+  ///   - padding: The distance between the leading edges of the two views.
+  ///   - view: The view to which the leading edge will be constrained. If `nil`, the view's superview is used.
+  ///   - safeArea: A Boolean indicating whether to constrain to the `safeAreaLayoutGuide` of the other view. If `true`, the constraint respects the safe area.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the leading edge constraint.
   @discardableResult
   public func leading(
     _ padding: CGFloat = 0,
@@ -25,6 +33,14 @@ extension UIView {
     return LayoutConstraints(leading: constraint)
   }
 
+  /// Constrains the view's trailing anchor to the trailing anchor of another view or its superview.
+  ///
+  /// - Parameters:
+  ///   - padding: The distance between the trailing edges of the two views.
+  ///   - view: The view to which the trailing edge will be constrained. If `nil`, the view's superview is used.
+  ///   - safeArea: A Boolean indicating whether to constrain to the `safeAreaLayoutGuide` of the other view. If `true`, the constraint respects the safe area.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the trailing edge constraint.
   @discardableResult
   public func trailing(
     _ padding: CGFloat = 0,
@@ -49,6 +65,14 @@ extension UIView {
     return LayoutConstraints(trailing: constraint)
   }
 
+  /// Constrains the view's top anchor to the top anchor of another view or its superview.
+  ///
+  /// - Parameters:
+  ///   - padding: The distance between the top edges of the two views.
+  ///   - view: The view to which the top edge will be constrained. If `nil`, the view's superview is used.
+  ///   - safeArea: A Boolean indicating whether to constrain to the `safeAreaLayoutGuide` of the other view. If `true`, the constraint respects the safe area.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the top edge constraint.
   @discardableResult
   public func top(
     _ padding: CGFloat = 0,
@@ -73,6 +97,14 @@ extension UIView {
     return LayoutConstraints(top: constraint)
   }
 
+  /// Constrains the view's bottom anchor to the bottom anchor of another view or its superview.
+  ///
+  /// - Parameters:
+  ///   - padding: The distance between the bottom edges of the two views.
+  ///   - view: The view to which the bottom edge will be constrained. If `nil`, the view's superview is used.
+  ///   - safeArea: A Boolean indicating whether to constrain to the `safeAreaLayoutGuide` of the other view. If `true`, the constraint respects the safe area.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the bottom edge constraint.
   @discardableResult
   public func bottom(
     _ padding: CGFloat = 0,
@@ -99,6 +131,14 @@ extension UIView {
 }
 
 extension UIView {
+  /// Constrains the view's leading and trailing edges to those of another view or its superview, effectively stretching it horizontally.
+  ///
+  /// - Parameters:
+  ///   - padding: The distance between the view's edges and the other view's edges.
+  ///   - view: The view to which the horizontal edges will be constrained. If `nil`, the view's superview is used.
+  ///   - safeArea: A Boolean indicating whether to constrain to the `safeAreaLayoutGuide` of the other view. If `true`, the constraints respect the safe area.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the leading and trailing constraints.
   @discardableResult
   public func horizontally(
     _ padding: CGFloat = 0,
@@ -111,6 +151,14 @@ extension UIView {
     }
   }
 
+  /// Constrains the view's top and bottom edges to those of another view or its superview, effectively stretching it vertically.
+  ///
+  /// - Parameters:
+  ///   - padding: The distance between the view's edges and the other view's edges.
+  ///   - view: The view to which the vertical edges will be constrained. If `nil`, the view's superview is used.
+  ///   - safeArea: A Boolean indicating whether to constrain to the `safeAreaLayoutGuide` of the other view. If `true`, the constraints respect the safe area.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the top and bottom constraints.
   @discardableResult
   public func vertically(
     _ padding: CGFloat = 0,
@@ -125,6 +173,14 @@ extension UIView {
 }
 
 extension UIView {
+  /// Constrains all four edges of the view to another view or its superview, optionally with padding and safe area considerations.
+  ///
+  /// - Parameters:
+  ///   - padding: The distance between the view's edges and the other view's edges.
+  ///   - view: The view to which the edges will be constrained. If `nil`, the view's superview is used.
+  ///   - safeArea: A Boolean indicating whether to constrain to the `safeAreaLayoutGuide` of the other view. If `true`, the constraints respect the safe area.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing top, leading, bottom and trailing constraints.
   @discardableResult
   public func allEdges(
     _ padding: CGFloat = 0,
@@ -139,7 +195,13 @@ extension UIView {
 }
 
 extension UIView {
-  /// Align the view after the passed view.
+  /// Constrains the view's leading anchor to the trailing anchor of another view, positioning it after the specified view horizontally.
+  ///
+  /// - Parameters:
+  ///   - view: The view after which this view will be positioned.
+  ///   - padding: The space between the trailing edge of the specified view and the leading edge of this view.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the leading edge constraint.
   @discardableResult
   public func after(
     _ view: UIView,
@@ -156,7 +218,13 @@ extension UIView {
     return LayoutConstraints(leading: constraint)
   }
 
-  /// Align the view before the passed view.
+  /// Constrains the view's trailing anchor to the leading anchor of another view, positioning it before the specified view horizontally.
+  ///
+  /// - Parameters:
+  ///   - view: The view before which this view will be positioned.
+  ///   - padding: The space between the leading edge of the specified view and the trailing edge of this view.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the trailing edge constraint.
   @discardableResult
   public func before(
     _ view: UIView,
@@ -173,7 +241,13 @@ extension UIView {
     return LayoutConstraints(trailing: constraint)
   }
 
-  /// Align the view below the passed view.
+  /// Constrains the view's top anchor to the bottom anchor of another view, positioning it below the specified view vertically.
+  ///
+  /// - Parameters:
+  ///   - view: The view below which this view will be positioned.
+  ///   - padding: The space between the bottom edge of the specified view and the top edge of this view.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the top edge constraint.
   @discardableResult
   public func below(
     _ view: UIView,
@@ -190,7 +264,13 @@ extension UIView {
     return LayoutConstraints(bottom: constraint)
   }
 
-  /// Align the view above the passed view.
+  /// Constrains the view's bottom anchor to the top anchor of another view, positioning it above the specified view vertically.
+  ///
+  /// - Parameters:
+  ///   - view: The view above which this view will be positioned.
+  ///   - padding: The space between the top edge of the specified view and the bottom edge of this view.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the bottom edge constraint.
   @discardableResult
   public func above(
     _ view: UIView,
@@ -209,6 +289,12 @@ extension UIView {
 }
 
 extension UIView {
+  /// Sets the view's width to a specific value.
+  ///
+  /// - Parameters:
+  ///   - value: The width value.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the width constraint.
   @discardableResult
   public func width(_ constant: CGFloat) -> LayoutConstraints {
     self.translatesAutoresizingMaskIntoConstraints = false
@@ -219,6 +305,12 @@ extension UIView {
     return LayoutConstraints(width: constraint)
   }
 
+  /// Sets the view's height to a specific value.
+  ///
+  /// - Parameters:
+  ///   - value: The height value.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the height constraint.
   @discardableResult
   public func height(_ constant: CGFloat) -> LayoutConstraints {
     self.translatesAutoresizingMaskIntoConstraints = false
@@ -229,21 +321,41 @@ extension UIView {
     return LayoutConstraints(height: constraint)
   }
 
+  /// Sets the view's size to specific width and height values.
+  ///
+  /// - Parameters:
+  ///   - width: The width value.
+  ///   - height: The height value.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the size constraints.
   @discardableResult
-  public func size(_ size: CGSize) -> LayoutConstraints {
+  public func size(width: CGFloat, height: CGFloat) -> LayoutConstraints {
     return LayoutConstraints.merged {
-      self.width(size.width)
-      self.height(size.height)
+      self.width(width)
+      self.height(height)
     }
   }
 
+  /// Sets the view's size to a specific width and height value.
+  ///
+  /// - Parameters:
+  ///   - constant: The height and width value.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the size constraints.
   @discardableResult
   public func size(_ constant: CGFloat) -> LayoutConstraints {
-    return self.size(CGSize(width: constant, height: constant))
+    return self.size(width: constant, height: constant)
   }
 }
 
 extension UIView {
+  /// Constrains the view's center Y anchor to the center Y anchor of another view or its superview.
+  ///
+  /// - Parameters:
+  ///   - offset: The vertical offset between the center Y anchors of the two views.
+  ///   - view: The view to which the center Y will be constrained. If `nil`, the view's superview is used.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the center Y constraint.
   @discardableResult
   public func centerVertically(
     offset: CGFloat = 0,
@@ -265,6 +377,13 @@ extension UIView {
     return LayoutConstraints(vertical: constraint)
   }
 
+  /// Constrains the view's center X anchor to the center X anchor of another view or its superview.
+  ///
+  /// - Parameters:
+  ///   - offset: The horizontal offset between the center X anchors of the two views.
+  ///   - view: The view to which the center X will be constrained. If `nil`, the view's superview is used.
+  ///
+  /// - Returns: A `LayoutConstraints` object containing the center X constraint.
   @discardableResult
   public func centerHorizontally(
     offset: CGFloat = 0,
@@ -286,6 +405,13 @@ extension UIView {
     return LayoutConstraints(horizontal: constraint)
   }
 
+  /// Constrains the view's center anchors to the center anchors of another view or its superview.
+  ///
+  /// - Parameters:
+  ///   - offset: The offset between the center anchors of the two views.
+  ///   - view: The view to which the center will be constrained. If `nil`, the view's superview is used.
+  ///
+  /// - Returns: A ``LayoutConstraints`` object containing the center X and center Y constraint.
   @discardableResult
   public func center(
     offset: CGPoint = .zero,