Update documentation of OptionPickerControl

Author: bcylin

CHANGELOG.md

@@ -1,3 +1,8 @@
+## `develop`
+
+* Drop Class Name Prefixes
+* Add an easy to use `OptionPickerControl` that displays a `UIPickerView` with given options
+
 ## v1.5.0
 
 * Swift 4.0

Example/Language.swift

@@ -51,7 +51,7 @@ enum Language: String, OptionDescriptive {
     return rawValue.capitalized
   }
 
-  static var optionalText: String {
+  static var titleForOptionalValue: String {
     return "(Optional)"
   }
 

Source/OptionPickerControl/Option.swift

@@ -1,6 +1,6 @@
 //
 //  Option.swift
-//  Flashcards
+//  ICInputAccessory
 //
 //  Created by Ben on 22/11/2017.
 //  Copyright © 2017 bcylin.
@@ -26,32 +26,38 @@
 
 import Foundation
 
+/// The protocol defines the required variables to be displayed in a `UIPickerView` via `OptionPickerControl`.
 public protocol OptionDescriptive: Equatable {
+  /// The text for the row in the `UIPickerView`.
   var title: String { get }
-  static var optionalText: String { get }
+  /// The text for a placeholder row when the picker selection is optional.
+  static var titleForOptionalValue: String { get }
 }
 
-////////////////////////////////////////////////////////////////////////////////
-
 
+/// An option struct that carries the `OptionDescriptive`
 public struct Option<T: OptionDescriptive>: Equatable {
 
   // MARK: - Initialization
 
+  /// Returns an option that displays the optional value of an `OptionDescriptive` type.
   public static func optional() -> Option<T> {
     return Option<T>()
   }
 
+  /// Returns an initialized option with an instance of an `OptionDescriptive` type.
   public init(_ value: T) {
     self.value = value
   }
 
   // MARK: - Properties
 
+  /// Conformance to `OptionDescriptive`.
   public var title: String {
-    return value?.title ?? T.optionalText
+    return value?.title ?? T.titleForOptionalValue
   }
 
+  /// The `OptionDescriptive` value of the option. Returns `nil` when it's the `optional` placeholder.
   public let value: T?
 
   // MARK: - Private
@@ -62,6 +68,7 @@ public struct Option<T: OptionDescriptive>: Equatable {
 
   // MARK: - Equatable
 
+  /// Returns true when two options' values are equal.
   public static func == (lhs: Option<T>, rhs: Option<T>) -> Bool {
     return lhs.value == rhs.value
   }

Source/OptionPickerControl/OptionPickerControl.swift

@@ -1,6 +1,6 @@
 //
 //  OptionPickerControl.swift
-//  Flashcards
+//  ICInputAccessory
 //
 //  Created by Ben on 27/11/2017.
 //  Copyright © 2017 bcylin.
@@ -26,24 +26,28 @@
 
 import UIKit
 
-open class OptionPickerControl<T: OptionDescriptive>: UIControl,
-  UIPickerViewDataSource,
-  UIPickerViewDelegate {
+/// A `UIControl` that displays a `UIPickerView` and notifies changed selection and via `UIControlEvents` `.valueChanged`.
+open class OptionPickerControl<T: OptionDescriptive>: UIControl, UIPickerViewDataSource, UIPickerViewDelegate {
 
   // MARK: - Initialization
 
+  /// Returns an initialized `OptionPickerControl`.
   public init() {
     super.init(frame: .zero)
     addSubview(hiddenTextField)
   }
 
+  /// Not supported. `OptionPickerControl` is not compatible with storyboards.
   required public init?(coder aDecoder: NSCoder) {
     fatalError("init(coder:) is not supported")
   }
 
   // MARK: - Properties
 
+  /// Options that shows in the `UIPickerView`.
   public var options: [Option<T>] = [Option<T>.optional()]
+
+  /// The currently selected item in the options.
   public var selectedOption: Option<T> = Option<T>.optional() {
     didSet {
       if hiddenTextField.isFirstResponder {
@@ -54,6 +58,14 @@ open class OptionPickerControl<T: OptionDescriptive>: UIControl,
     }
   }
 
+  /// A reference to the displayed `UIPickerView` for customization.
+  public private(set) lazy var picker: UIPickerView = {
+    let picker = UIPickerView()
+    picker.dataSource = self
+    picker.delegate = self
+    return picker
+  }()
+
   // MARK: - Lazy Instantiation
 
   private lazy var doneBarButton: UIBarButtonItem =
@@ -68,13 +80,6 @@ open class OptionPickerControl<T: OptionDescriptive>: UIControl,
     return toolbar
   }()
 
-  private lazy var picker: UIPickerView = {
-    let picker = UIPickerView()
-    picker.dataSource = self
-    picker.delegate = self
-    return picker
-  }()
-
   private lazy var hiddenTextField: UITextField = {
     let textField = UITextField()
     textField.inputAccessoryView = self.pickerToolbar
@@ -96,6 +101,7 @@ open class OptionPickerControl<T: OptionDescriptive>: UIControl,
 
   // MARK: - UIPickerViewDataSource
 
+  /// Currently `OptionPickerControl` only supports one component.
   open func numberOfComponents(in pickerView: UIPickerView) -> Int {
     return 1
   }