Add docstrings

iwasrobbed · May 25, 2016 · 45e0455 · 45e0455
1 parent 0f7c650
commit 45e0455
Show file tree

Hide file tree

Showing 6 changed files with 93 additions and 2 deletions.
diff --git a/LazyObject.podspec b/LazyObject.podspec
@@ -1,7 +1,7 @@
 Pod::Spec.new do |spec|
   spec.name         = "LazyObject"
   spec.summary      = "Lazy JSON deserialization in Swift"
-  spec.version      = "0.2"
+  spec.version      = "0.2.1"
   spec.homepage     = "https://github.com/iwasrobbed/LazyObject"
   spec.license      = { :type => "MIT", :file => "LICENSE" }
   spec.authors      = { "Rob Phillips" => "rob@desideratalabs.co" }

diff --git a/README.md b/README.md
@@ -59,7 +59,7 @@ Any of your base or sub-classes can conform to *one* of the supported protocols:
 
 * ISO8601Formattable (e.g. "2016-04-24T14:42:42.424Z")
 * RFC3339Formattable (e.g. "2016-04-24T14:42:42Z")
-* RFC1123Formattable (e.g. "Sun, 24 Apr 2016 14:42:42 +0000"")
+* RFC1123Formattable (e.g. "Sun, 24 Apr 2016 14:42:42 +0000")
 * RFC850Formattable (e.g. "Sunday, 24-Apr-16 14:42:42 UTC")
 * EpochFormattable (e.g. "1461508962.424" as a string or 1461508962.424 as a double)
 

diff --git a/Source/Date Formatting/LazyDateFormattable.swift b/Source/Date Formatting/LazyDateFormattable.swift
@@ -63,15 +63,51 @@ extension EpochFormattable {
 
 public protocol LazyDateFormattable {
 
+    /**
+     Retrieves an `NSDate`, transformed based on the type of `LazyDateFormattable` that was used
+
+     - parameter keyPath: The key / key path to get the date for
+
+     - throws: A `LazyMappingError` depending on the circumstances
+
+     - returns: An `NSDate` object, converted using a `LazyDateFormattable` protocol; using `try!` will force it whereas `try?` will safely return `nil` if it failed.
+     */
     @warn_unused_result
     func dateFor(keyPath: String) throws -> NSDate
 
+    /**
+     Retrieves an `NSDate`, transformed based on the type of `LazyDateFormattable` that was used
+
+     - parameter getter: The `#function` to get (e.g. for a property named `name`, specifying #function will convert it to a string of `name`)
+
+     - throws: A `LazyMappingError` depending on the circumstances
+
+     - returns: An `NSDate` object, converted using a `LazyDateFormattable` protocol; using `try!` will force it whereas `try?` will safely return `nil` if it failed.
+     */
     @warn_unused_result
     func dateFor(getter: Selector) throws -> NSDate
 
+    /**
+     Converts the given date time string to an `NSDate` based on the type of formattable used
+
+     - parameter dateString: The date time string to convert
+
+     - throws: A `LazyMappingError` depending on the circumstances
+
+     - returns: An `NSDate`
+     */
     @warn_unused_result
     func convertToDate(dateString: String) throws -> NSDate
 
+    /**
+     Converts the given epoch time to an `NSDate`
+
+     - parameter epoch: A double representing the epoch time
+
+     - throws: A `LazyMappingError` depending on the circumstances
+
+     - returns: An `NSDate`
+     */
     @warn_unused_result
     func convertToDate(epoch: Double) throws -> NSDate
 
@@ -81,11 +117,29 @@ public protocol LazyDateFormattable {
 
 public extension LazyDateFormattable {
 
+    /**
+     Converts the given date time string to an `NSDate` based on the type of formattable used
+
+     - parameter dateString: The date time string to convert
+
+     - throws: A `LazyMappingError` depending on the circumstances
+
+     - returns: An `NSDate`
+     */
     @warn_unused_result
     public func convertToDate(dateString: String) throws -> NSDate {
         throw LazyMappingError.CustomError(message: "Must use one of the specialized LazyDateFormattable protocols (e.g. ISO8601Formattable)")
     }
 
+    /**
+     Converts the given epoch time to an `NSDate`
+
+     - parameter epoch: A double representing the epoch time
+
+     - throws: A `LazyMappingError` depending on the circumstances
+
+     - returns: An `NSDate`
+     */
     @warn_unused_result
     public func convertToDate(epoch: Double) throws -> NSDate {
         throw LazyMappingError.CustomError(message: "Must use the specialized EpochFormattable protocol")

diff --git a/Source/Date Formatting/NSDate+Formatters.swift b/Source/Date Formatting/NSDate+Formatters.swift
@@ -44,18 +44,30 @@ extension NSDate {
 
         // Note: Epoch (Unix) timestamps are handled directly in convertibles, not as a formatter
 
+        /**
+          E.g. 2016-04-24T14:42:42.424Z
+        */
         static let iso8601: NSDateFormatter = {
             return NSDateFormatter.Lazy.formatterFrom("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'")
         }()
 
+        /**
+          E.g. 2016-04-24T14:42:42Z
+         */
         static let rfc3339: NSDateFormatter = {
             return NSDateFormatter.Lazy.formatterFrom("yyyy-MM-dd'T'HH:mm:ss'Z'")
         }()
 
+        /**
+          E.g. Sun, 24 Apr 2016 14:42:42 +0000
+         */
         static let rfc1123: NSDateFormatter = {
             return NSDateFormatter.Lazy.formatterFrom("EEE, dd MMM yyyy HH:mm:ss zzz")
         }()
 
+        /**
+          E.g. Sunday, 24-Apr-16 14:42:42 UTC
+         */
         static let rfc850: NSDateFormatter = {
             return NSDateFormatter.Lazy.formatterFrom("EEEE, dd-MMM-yy HH:mm:ss zzz")
         }()

diff --git a/Source/Date Formatting/NSDateFormatter+Lazy.swift b/Source/Date Formatting/NSDateFormatter+Lazy.swift
@@ -12,6 +12,13 @@ extension NSDateFormatter {
 
     public struct Lazy {
 
+        /**
+         Creates a formatter for use with date string conversions
+
+         - parameter string: The format string to parse the date with
+
+         - returns: An `NSDateFormatter` with UTC timezone and `en_US_POSIX` locale
+         */
         static func formatterFrom(string: String) -> NSDateFormatter {
             let formatter = NSDateFormatter()
             formatter.dateFormat = string

diff --git a/Source/LazyMapping.swift b/Source/LazyMapping.swift
@@ -119,11 +119,29 @@ public extension LazyMapping {
 
 public extension LazyMapping where Self: LazyDateFormattable {
 
+    /**
+     Retrieves an `NSDate`, transformed based on the type of `LazyDateFormattable` that was used
+
+     - parameter getter: The `#function` to get (e.g. for a property named `name`, specifying #function will convert it to a string of `name`)
+
+     - throws: A `LazyMappingError` depending on the circumstances
+
+     - returns: An `NSDate` object, converted using a `LazyDateFormattable` protocol; using `try!` will force it whereas `try?` will safely return `nil` if it failed.
+     */
     @warn_unused_result
     public func dateFor(getter: Selector) throws -> NSDate {
         return try dateFor(NSStringFromSelector(getter))
     }
 
+    /**
+     Retrieves an `NSDate`, transformed based on the type of `LazyDateFormattable` that was used
+
+     - parameter keyPath: The key / key path to get the date for
+
+     - throws: A `LazyMappingError` depending on the circumstances
+
+     - returns: An `NSDate` object, converted using a `LazyDateFormattable` protocol; using `try!` will force it whereas `try?` will safely return `nil` if it failed.
+     */
     @warn_unused_result
     public func dateFor(keyPath: String) throws -> NSDate {
         let dateValue: AnyObject = try objectFor(keyPath)