Merge pull request #3 from graycampbell/docs

Update country picker implementation and documentation

GCCountryPicker/GCCountry.swift

@@ -9,18 +9,39 @@ import UIKit
 
 // MARK: Properties & Initializers
 
+/// A structure that contains the ISO 3166-1 alpha-2 country code and the localized display name for a country.
+
 public struct GCCountry {
 
     // MARK: Properties
 
+    /// The ISO 3166-1 alpha-2 code for the country.
+
     public let countryCode: String!
+
+    /// The localized display name for the country.
+    ///
+    /// This value is automatically generated using the supplied country code and the current locale.
+
     public let localizedDisplayName: String!
 
     // MARK: Initializers
 
-    public init(countryCode: String) {
+    /// Initializes and returns a newly allocated country.
+    ///
+    /// - Parameter countryCode: An ISO 3166-1 alpha-2 code representing a country.
+    /// - Returns: An initialized country containing a country code and a localized display name.
+
+    public init?(countryCode: String) {
 
-        self.countryCode = countryCode
-        self.localizedDisplayName = Locale.current.localizedString(forRegionCode: countryCode)
+        if let localizedDisplayName = Locale.current.localizedString(forRegionCode: countryCode) {
+
+            self.countryCode = countryCode
+            self.localizedDisplayName = localizedDisplayName
+        }
+        else {
+
+            return nil
+        }
     }
 }

GCCountryPicker/GCCountryPickerDelegate.swift

@@ -13,8 +13,6 @@ public protocol GCCountryPickerDelegate {
 
     /// Tells the delegate that the user cancelled the pick operation.
     ///
-    /// ---
-    ///
     /// Your delegate’s implementation of this method should dismiss the country picker.
     ///
     /// - Parameter countryPicker: The controller object managing the country picker interface.
@@ -23,8 +21,6 @@ public protocol GCCountryPickerDelegate {
 
     /// Tells the delegate that the user picked a country.
     ///
-    /// ---
-    ///
     /// Your delegate’s implementation of this method should pass the country on to any custom code that needs it, and then it should dismiss the picker view.
     ///
     /// - Parameter countryPicker: The controller object managing the country picker interface.

GCCountryPicker/GCCountryPickerViewController.swift

@@ -20,27 +20,60 @@ public final class GCCountryPickerViewController: UITableViewController {
     public var delegate: GCCountryPickerDelegate?
 
     fileprivate var countries = [GCCountry]()
+    fileprivate var countryCodes = [String]()
     fileprivate var searchController: UISearchController!
     fileprivate var searchResultsController = GCSearchResultsController()
 
+    fileprivate var defaultCountryCodes: [String] {
+
+        if let url = Bundle(for: GCCountryPickerViewController.self).url(forResource: "CountryCodes", withExtension: "plist") {
+
+            if let countryCodes = NSArray(contentsOf: url) as? [String] {
+
+                return countryCodes
+            }
+        }
+
+        return []
+    }
+
     // MARK: Initializers
 
+    /// Returns an object initialized from data in a given unarchiver.
+    ///
+    /// - Parameter coder: An unarchiver object.
+    /// - Returns: self, initialized using the data in decoder.
+
+    public required init?(coder aDecoder: NSCoder) {
+
+        super.init(coder: aDecoder)
+
+        self.countryCodes = self.defaultCountryCodes
+    }
+
     /// Initializes and returns a newly allocated country picker view controller object.
     ///
+    /// By default, the country picker interface displays the 249 countries that have been officially assigned ISO 3166-1 alpha-2 codes as part of the ISO 3166 standard. You can customize which countries the country picker interface displays by initializing the controller with a collection of ISO 3166-1 alpha-2 country codes.
+    ///
+    /// - Parameter countryCodes: A collection of ISO 3166-1 alpha-2 country codes representing countries for the country picker interface to display.
     /// - Returns: An initialized country picker view controller object.
 
-    public convenience init() {
+    public init(countryCodes: [String]? = nil) {
 
-        self.init(style: .plain)
+        super.init(style: .plain)
 
-        self.navigationItem.title = "Country"
+        self.countryCodes = countryCodes ?? self.defaultCountryCodes
     }
 }
 
 // MARK: - View
 
 extension GCCountryPickerViewController {
 
+    /// Called after the controller'€™s view is loaded into memory.
+    ///
+    /// This method is called after the view controller has loaded its view hierarchy into memory. This method is called regardless of whether the view hierarchy was loaded from a nib file or created programmatically in the loadView() method. You usually override this method to perform additional initialization on views that were loaded from nib files.
+
     public override func viewDidLoad() {
 
         super.viewDidLoad()
@@ -57,20 +90,15 @@ extension GCCountryPickerViewController {
 
     fileprivate func loadCountries() {
 
-        if let url = Bundle(for: GCCountryPickerViewController.self).url(forResource: "CountryCodes", withExtension: "plist") {
+        for countryCode in self.countryCodes {
 
-            if let countryCodes = NSArray(contentsOf: url) as? [String] {
-
-                for countryCode in countryCodes {
-
-                    let country = GCCountry(countryCode: countryCode)
-
-                    self.countries.append(country)
-                }
-
-                self.countries.sort(by: { $0.localizedDisplayName < $1.localizedDisplayName })
+            if let country = GCCountry(countryCode: countryCode) {
+
+                self.countries.append(country)
             }
         }
+
+        self.countries.sort(by: { $0.localizedDisplayName < $1.localizedDisplayName })
     }
 }
 
@@ -104,6 +132,12 @@ extension GCCountryPickerViewController {
 
 extension GCCountryPickerViewController: UISearchResultsUpdating {
 
+    /// Called when the search bar becomes the first responder or when the user makes changes inside the search bar.
+    ///
+    /// This method is automatically called whenever the search bar becomes the first responder or changes are made to the text in the search bar. Perform any required filtering and updating inside of this method.
+    ///
+    /// - Parameter searchController: The UISearchController object used as the search bar.
+
     public func updateSearchResults(for searchController: UISearchController) {
 
         var searchResults = [GCCountry]()
@@ -144,11 +178,24 @@ extension GCCountryPickerViewController {
 
 extension GCCountryPickerViewController {
 
+    /// Tells the data source to return the number of rows in a given section of a table view.
+    ///
+    /// - Parameter tableView: The table-view object requesting this information.
+    /// - Parameter section: An index number identifying a section in tableView.
+    /// - Returns: The number of rows in section.
+
     public override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
 
         return self.countries.count
     }
 
+    /// Tells the delegate that the specified row is now selected.
+    ///
+    /// The delegate handles selections in this method. One of the things it can do is exclusively assign the check-mark image (checkmark) to one row in a section (radio-list style). This method isn’t called when the isEditing property of the table is set to true (that is, the table view is in editing mode). See "€œManaging Selections" in Table View Programming Guide for iOS for further information (and code examples) related to this method.
+    ///
+    /// - Parameter tableView: A table-view object informing the delegate about the new row selection.
+    /// - Parameter indexPath: An index path locating the new selected row in tableView.
+
     public override func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
 
         self.delegate?.countryPicker(self, didSelectCountry: self.countries[indexPath.row])
@@ -159,6 +206,14 @@ extension GCCountryPickerViewController {
 
 extension GCCountryPickerViewController {
 
+    /// Asks the data source for a cell to insert in a particular location of the table view.
+    ///
+    /// The returned UITableViewCell object is frequently one that the application reuses for performance reasons. You should fetch a previously created cell object that is marked for reuse by sending a dequeueReusableCell(withIdentifier:) message to tableView. Various attributes of a table cell are set automatically based on whether the cell is a separator and on information the data source provides, such as for accessory views and editing controls.
+    ///
+    /// - Parameter tableView: A table-view object requesting the cell.
+    /// - Parameter indexPath: An index path locating a row in tableView.
+    /// - Returns: An object inheriting from UITableViewCell that the table view can use for the specified row. An assertion is raised if you return nil.
+
     public override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
 
         let cell = tableView.dequeueReusableCell(withIdentifier: "TableViewCell", for: indexPath)

GCCountryPicker/GCSearchResultsController.swift

@@ -19,6 +19,8 @@ class GCSearchResultsController: UITableViewController {
 
     var delegate: GCSearchResultsDelegate?
 
+    /// An ordered collection of search results displayed by the controller.
+
     var searchResults = [GCCountry]() {
 
         didSet {