Bring back comments from PinLayout commented interface

Sources/Impl/PinLayoutImpl+Layouting.swift

@@ -25,6 +25,16 @@
 
 // MARK: UIView's frame computation methods
 extension PinLayout {
+    /**
+     The method will execute PinLayout commands immediately. This method is **required only if your
+     source codes should also work in Xcode Playgrounds**. Outside of playgrounds, PinLayout executes
+     this method implicitly, it is not necessary to call it.
+
+     Examples:
+     ```swift
+     view.pin.top(20).width(100).layout()
+     ```
+     */
     public func layout() {
         apply()
     }

Sources/Impl/PinLayoutImpl+Size.swift

@@ -94,16 +94,43 @@ extension PinLayout {
         return setSize(view.getRect(keepTransform: keepTransform).size, context)
     }
 
+    /**
+     Set the view aspect ratio.
+
+     AspectRatio is applied only if a single dimension (either width or height) can be determined,
+     in that case the aspect ratio will be used to compute the other dimension.
+
+     * AspectRatio is defined as the ratio between the width and the height (width / height).
+     * An aspect ratio of 2 means the width is twice the size of the height.
+     * AspectRatio respects the min (minWidth/minHeight) and the max (maxWidth/maxHeight)
+     dimensions of an item.
+     */
     @discardableResult
     public func aspectRatio(_ ratio: CGFloat) -> PinLayout {
         return setAdjustSizeType(.aspectRatio(ratio), { "aspectRatio(\(ratio))" })
     }
 
+    /**
+     Set the view aspect ratio using another UIView's aspect ratio.
+
+     AspectRatio is applied only if a single dimension (either width or height) can be determined,
+     in that case the aspect ratio will be used to compute the other dimension.
+
+     * AspectRatio is defined as the ratio between the width and the height (width / height).
+     * AspectRatio respects the min (minWidth/minHeight) and the max (maxWidth/maxHeight)
+     dimensions of an item.
+     */
     public func aspectRatio(of view: View) -> PinLayout {
         let rect = view.getRect(keepTransform: keepTransform)
         return setAdjustSizeType(.aspectRatio(rect.width / rect.height), { "aspectRatio(of: \(viewDescription(view)))" })
     }
 
+    /**
+     If the layouted view is an UIImageView, this method will set the aspectRatio using
+     the UIImageView's image dimension.
+
+     For other types of views, this method as no impact.
+     */
     #if os(iOS) || os(tvOS)
     public func aspectRatio() -> PinLayout {
         func context() -> String { return "aspectRatio()" }
@@ -121,12 +148,71 @@ extension PinLayout {
     }
     #endif
 
+    /**
+     The method adjust the view's size based on the view's `sizeThatFits()` method result.
+     PinLayout will adjust either the view's width or height based on the `fitType` parameter value.
+
+     Notes:
+     * If margin rules apply, margins will be applied when determining the reference dimension (width/height).
+     * The resulting size will always respect `minWidth` / `maxWidth` / `minHeight` / `maxHeight`.
+
+     - Parameter fitType: Identify the reference dimension (width / height) that will be used
+     to adjust the view's size:
+
+     .width: The method adjust the view's size based on the **reference width**.
+     * If properties related to the width have been pinned (e.g: width, left & right, margins, ...),
+     the **reference width will be determined by these properties**, if not the **current view's width**
+     will be used.
+     * The resulting width will always **match the reference width**.
+
+     .height: The method adjust the view's size based on the **reference height**.
+     * If properties related to the height have been pinned (e.g: height, top & bottom, margins, ...),
+     the **reference height will be determined by these properties**, if not the **current view's height**
+     will be used.
+     * The resulting height will always **match the reference height**.
+
+     .widthFlexible: Similar to `.width`, except that PinLayout won't constrain the resulting width to
+     match the reference width. The resulting width may be smaller or bigger depending on the view's
+     sizeThatFits(..) method result. For example a single line UILabel may returns a smaller width if its
+     string is smaller than the reference width.
+
+     .heightFlexible: Similar to `.height`, except that PinLayout won't constrain the resulting height to
+     match the reference height. The resulting height may be smaller or bigger depending on the view's
+     sizeThatFits(..) method result.
+
+     Examples:
+
+     ```
+     // Adjust the view's size based on a width of 100 pixels.
+     // The resulting width will always match the pinned property `width(100)`.
+     view.pin.width(100).sizeToFit(.width)
+
+     // Adjust the view's size based on view's current width.
+     // The resulting width will always match the view's original width.
+     // The resulting height will never be bigger than the specified `maxHeight`.
+     view.pin.sizeToFit(.width).maxHeight(100)
+
+     // Adjust the view's size based on 100% of the superview's height.
+     // The resulting height will always match the pinned property `height(100%)`.
+     view.pin.height(100%).sizeToFit(.height)
+
+     // Adjust the view's size based on view's current height.
+     // The resulting width will always match the view's original height.
+     view.pin.sizeToFit(.height)
+
+     // Since `.widthFlexible` has been specified, its possible that the resulting
+     // width will be smaller or bigger than 100 pixels, based of the label's sizeThatFits()
+     // method result.
+     label.pin.width(100).sizeToFit(.widthFlexible)
+     ```
+     */
     @available(OSX 10.10, *)
     public func sizeToFit(_ fitType: FitType) -> PinLayout {
         return setAdjustSizeType(fitType.toAdjustSizeType(), { return "sizeToFit(\(fitType.description))" })
     }
 
     #if os(iOS) || os(tvOS)
+    @available(*, deprecated, message: "fitSize() is deprecated, please use sizeToFit(fitType: FitType)")
     public func fitSize() -> PinLayout {
         return setAdjustSizeType(.fitSizeLegacy, { return "fitSize()" })
     }

Sources/Impl/PinLayoutImpl+WrapContent.swift

@@ -24,26 +24,61 @@ import AppKit
 #endif
 
 extension PinLayout {
+    /**
+     Adjust the view's width & height to wrap all its subviews. The method also adjust subviews position to create a tight wrap.
+     */
     public func wrapContent() -> PinLayout {
         return wrapContent(.all, padding: PEdgeInsets(top: 0, left: 0, bottom: 0, right: 0), { return "wrapContent()" })
     }
 
+    /**
+     Adjust the view's width & height to wrap all its subviews. The method also adds a padding around all subviews.
+
+     - Parameters:
+     - padding: Specify a padding value.
+     */
     public func wrapContent(padding: CGFloat) -> PinLayout {
         return wrapContent(.all, padding: PEdgeInsets(top: padding, left: padding, bottom: padding, right: padding), { return "wrapContent(padding: \(padding)" })
     }
 
+    /**
+     Adjust the view's width & height to wrap all its subviews. The method also adds a padding around all subviews.
+
+     - Parameters:
+     - padding: Specify a padding using an UIEdgeInsets.
+     */
     public func wrapContent(padding: PEdgeInsets) -> PinLayout {
         return wrapContent(.all, padding: padding, { return "wrapContent(padding: \(insetsDescription(padding))" })
     }
 
+    /**
+     Adjust the view's width AND/OR height to wrap all its subviews.
+
+     - Parameters:
+     - type: Specify the wrap type (.all, .horizontally, .vertically)
+     */
     public func wrapContent(_ type: WrapType) -> PinLayout {
         return wrapContent(type, padding: PEdgeInsets(top: 0, left: 0, bottom: 0, right: 0), { return "wrapContent(\(type.description)" })
     }
 
+    /**
+     Adjust the view's width AND/OR height to wrap all its subviews. The method also adds a padding around all subviews.
+
+     - Parameters:
+     - type: Specify the wrap type (.all, .horizontally, .vertically)
+     - padding: Specify a padding value.
+     */
     public func wrapContent(_ type: WrapType, padding: CGFloat) -> PinLayout {
         return wrapContent(type, padding: PEdgeInsets(top: padding, left: padding, bottom: padding, right: padding), { return "wrapContent(\(type.description), padding: \(padding)" })
     }
 
+    /**
+     Adjust the view's width AND/OR height to wrap all its subviews. The method also adds a padding around all subviews.
+
+     - Parameters:
+     - type: Specify the wrap type (.all, .horizontally, .vertically)
+     - padding: Specify a padding using an UIEdgeInsets.
+     */
     public func wrapContent(_ type: WrapType, padding: PEdgeInsets) -> PinLayout {
         return wrapContent(type, padding: padding, { return "wrapContent(\(type.description), padding: \(insetsDescription(padding))" })
     }