From e4fa1c779e32f71adc384b29f864a0143c39e3a7 Mon Sep 17 00:00:00 2001 From: Wagner Truppel Date: Mon, 16 Oct 2017 12:16:35 +0100 Subject: [PATCH] Added documentation to all exposed public entities. --- .../Public API/DrawerConfiguration.swift | 51 +++++++++++++++++++ .../Public API/DrawerDisplayController.swift | 17 ++++++- .../Public API/DrawerPresentable.swift | 2 + .../Public API/DrawerPresenting.swift | 3 ++ 4 files changed, 72 insertions(+), 1 deletion(-) diff --git a/DrawerKit/DrawerKit/Public API/DrawerConfiguration.swift b/DrawerKit/DrawerKit/Public API/DrawerConfiguration.swift index e497957..6857054 100644 --- a/DrawerKit/DrawerKit/Public API/DrawerConfiguration.swift +++ b/DrawerKit/DrawerKit/Public API/DrawerConfiguration.swift @@ -4,23 +4,74 @@ import UIKit /// See `DrawerDisplayController+Configuration.swift` for documentation on /// what the various parameters are used for. public struct DrawerConfiguration: Equatable { + /// How long the animations that move the drawer up and down last. + /// The default value is 0.8 seconds. public var durationInSeconds: TimeInterval + + /// The type of timing curve to use for the animations. The full set + /// of cubic Bezier curves and spring-based curves is supported. Note + /// that selecting a spring-based timing curve causes the `durationInSeconds` + /// parameter to be ignored, because the duration is computed based on the + /// specifics of the spring-based curve. The default is `UISpringTimingParameters()`, + /// which is the system's global spring-based timing curve. public var timingCurveProvider: UITimingCurveProvider + /// When `true`, the drawer is presented first in its partially expanded state. + /// When `false`, the presentation is always to full screen and there is no + /// partially expanded state. The default value is `true`. public var supportsPartialExpansion: Bool + + /// When `true`, dismissing the drawer from its fully expanded state can result + /// in the drawer stopping at its partially expanded state. When `false`, the + /// dismissal is always straight to the collapsed state. Note that + /// `supportsPartialExpansion` being `false` implies `dismissesInStages` being + /// `false` as well but you can have `supportsPartialExpansion == true` and + /// `dismissesInStages == false`, which would result in presentations to the + /// partially expanded state but all dismissals would be straight to the collapsed + /// state. The default value is `true`. public var dismissesInStages: Bool + + /// Whether or not the drawer can be dragged up and down. The default value is `true`. public var isDrawerDraggable: Bool + /// Whether or not the drawer can be dismissed by tapping anywhere outside of it. + /// The default value is `true`. public var isDismissableByOutsideDrawerTaps: Bool + + /// How many taps are required for dismissing the drawer by tapping outside of it. + /// The default value is 1. public var numberOfTapsForOutsideDrawerDismissal: Int + /// How fast one needs to "flick" the drawer up or down to make it ignore the + /// partially expanded state. Flicking fast enough up always presents to full screen + /// and flicking fast enough down always collapses the drawer. A typically good value + /// is around 3 points per screen height per second, and that is also the default + /// value of this property. public var flickSpeedThreshold: CGFloat + /// There is a band around the partially expanded position of the drawer where + /// ending a drag inside will cause the drawer to move back to the partially + /// expanded position (subjected to the conditions set by `supportsPartialExpansion` + /// and `dismissesInStages`, of course). Set `inDebugMode` to `true` to see lines + /// drawn at those positions. This value represents the gap *above* the partially + /// expanded position. The default value is 40 points. public var upperMarkGap: CGFloat + + /// There is a band around the partially expanded position of the drawer where + /// ending a drag inside will cause the drawer to move back to the partially + /// expanded position (subjected to the conditions set by `supportsPartialExpansion` + /// and `dismissesInStages`, of course). Set `inDebugMode` to `true` to see lines + /// drawn at those positions. This value represents the gap *below* the partially + /// expanded position. The default value is 40 points. public var lowerMarkGap: CGFloat + /// The animating drawer also animates the radius of its top left and top right + /// corners, from 0 to the value of this property. Setting this to 0 prevents any + /// corner animations from taking place. The default value is 15 points. public var maximumCornerRadius: CGFloat + + /// Initialiser for `DrawerConfiguration`. public init(durationInSeconds: TimeInterval = 0.3, timingCurveProvider: UITimingCurveProvider = UISpringTimingParameters(), supportsPartialExpansion: Bool = true, diff --git a/DrawerKit/DrawerKit/Public API/DrawerDisplayController.swift b/DrawerKit/DrawerKit/Public API/DrawerDisplayController.swift index 2edab97..c24bae8 100755 --- a/DrawerKit/DrawerKit/Public API/DrawerDisplayController.swift +++ b/DrawerKit/DrawerKit/Public API/DrawerDisplayController.swift @@ -5,14 +5,29 @@ import UIKit // - support insufficiently tall content // - support not-covering status bar and/or having a gap at the top +/// Instances of this class are returned as part of the `DrawerPresenting` protocol. public final class DrawerDisplayController: NSObject { - public let configuration: DrawerConfiguration // intentionally immutable + /// The collection of configurable parameters dictating how the drawer works. + public let configuration: DrawerConfiguration weak var presentingVC: (UIViewController & DrawerPresenting)? /* strong */ var presentedVC: (UIViewController & DrawerPresentable) let inDebugMode: Bool + /// Initialiser for `DrawerDisplayController`. + /// + /// - Parameters: + /// - presentingViewController: + /// the view controller presenting the drawer. + /// - presentedViewController: + /// the view controller wanting to be presented as a drawer. + /// - configuration: + /// the collection of configurable parameters dictating how the drawer works. + /// - inDebugMode: + /// a boolean value which, when true, draws guiding lines on top of the + /// presenting view controller but below the presented view controller. + /// Its default value is false. public init(presentingViewController: (UIViewController & DrawerPresenting), presentedViewController: (UIViewController & DrawerPresentable), configuration: DrawerConfiguration = DrawerConfiguration(), diff --git a/DrawerKit/DrawerKit/Public API/DrawerPresentable.swift b/DrawerKit/DrawerKit/Public API/DrawerPresentable.swift index 8d386ad..86bf4fa 100644 --- a/DrawerKit/DrawerKit/Public API/DrawerPresentable.swift +++ b/DrawerKit/DrawerKit/Public API/DrawerPresentable.swift @@ -2,5 +2,7 @@ import UIKit /// Protocol that view controllers presented inside a drawer must conform to. public protocol DrawerPresentable: class { + /// The height at which the drawer must be presented when it's in its + /// partially expanded state. If negative, its value is clamped to zero. var heightOfPartiallyExpandedDrawer: CGFloat { get } } diff --git a/DrawerKit/DrawerKit/Public API/DrawerPresenting.swift b/DrawerKit/DrawerKit/Public API/DrawerPresenting.swift index 207d174..661f91f 100644 --- a/DrawerKit/DrawerKit/Public API/DrawerPresenting.swift +++ b/DrawerKit/DrawerKit/Public API/DrawerPresenting.swift @@ -2,5 +2,8 @@ import UIKit /// Protocol that view controllers presenting a drawer must conform to. public protocol DrawerPresenting: class { + /// An object vended by the presenting view controller, whose responsibility + /// is to coordinate the presentation, animation, and interactivity of/with + /// the drawer. var drawerDisplayController: DrawerDisplayController? { get } }