Updated units and documentation

Author: sxg

README.md

@@ -70,6 +70,8 @@ The following units are supported:
 - UK
 - Auto (uses the local units for the location for which you are requesting weather data)
 
+More details about the units of each property are available [in the Dark Sky API docs](https://darksky.net/dev/docs/forecast).
+
 You can also choose the language that you want `Forecast` responses to use:
 
 ```swift

Source/DataPoint.swift

@@ -11,49 +11,49 @@ import Foundation
 /// Weather data for a specific location and time.
 public struct DataPoint {
 
-    /// The time at which this `DataPoint` occurs.
+    /// The time at which this `DataPoint` begins. `minutely` `DataPoint`s are always aligned to the top of the minute, `hourly` `DataPoint`s to the top of the hour, and `daily` `DataPoint`s to midnight of the day, all according to the local timezone.
     public let time: Date
 
-    /// A human-readable text summary of the weather.
+    /// A human-readable text summary of this `DataPoint`.
     public let summary: String?
 
-    /// A machine-readable summary of the weather suitable for selecting an icon for display.
+    /// A machine-readable text summary of this data point, suitable for selecting an icon for display.
     public let icon: Icon?
 
-    /// The time of the last sunrise before the solar noon closest to local noon on the given day. Only defined on `Forecast`'s `daily` `DataPoint`s. Note: near the poles, this may occur on a different day entirely!
+    /// The time when the sun will rise during a given day. Only defined on `Forecast`'s `daily` `DataPoint`s.
     public let sunriseTime: Date?
 
-    /// The time of the first sunset after the solar noon closest to local noon on the given day. Only defined on `Forecast`'s `daily` `DataPoint`s. Note: near the poles, this may occur on a different day entirely!
+    /// The time when the sun will set during a given day. Only defined on `Forecast`'s `daily` `DataPoint`s.
     public let sunsetTime: Date?
 
-    /// The fractional part of the lunation number of the given day. This can be thought of as the "percentage complete" of the current lunar month. A value of `0` represents a new moon, a value of `0.25` represents a first quarter moon, a value of `0.5` represents a full moon, and a value of `0.75` represents a last quarter moon. The ranges between these values represent waxing crescent, waxing gibbous, waning gibbous, and waning crescent moons, respectively. Only defined on `Forecast`'s `daily` `DataPoint`s.
+    /// The fractional part of the lunation number during the given day: a value of `0` corresponds to a new moon, `0.25` to a first quarter moon, `0.5` to a full moon, and `0.75` to a last quarter moon. The ranges in between these represent waxing crescent, waxing gibbous, waning gibbous, and waning crescent moons, respectively. Only defined on `Forecast`'s `daily` `DataPoint`s.
     public let moonPhase: Float?
 
-    /// The distance to the nearest storm in miles. This value is *very approximate* and should not be used in scenarios requiring accurate results. A storm distance of `0` doesn't necessarily refer to a storm at the requested location, but rather a storm in the vicinity of the requested location. Only defined on `Forecast`'s `currently` `DataPoint`s.
+    /// The approximate distance to the nearest storm. A storm distance of `0` doesn't necessarily refer to a storm at the requested location, but rather a storm in the vicinity of that location. Only defined on `Forecast`'s `currently` `DataPoint`s.
     public let nearestStormDistance: Float?
 
-    /// The direction of the nearest storm in degrees, with true north at 0º and progressing clockwise. If `nearestStormDistance` is `0`, then this value will be `nil`. The caveats that apply to `nearestStormDistance` apply to this too. Only defined on `Forecast`'s `currently` `DataPoint`s.
+    /// The approximate direction of the nearest storm in degrees, with true north at 0º and progressing clockwise. If `nearestStormDistance` is `0`, then this value will be `nil`. Only defined on `Forecast`'s `currently` `DataPoint`s.
     public let nearestStormBearing: Float?
 
-    /// The average expected intensity in inches of liquid water per hour of precipitation occurring at the given time *conditional on probability* (assuming any precipitation occurs at all). A *very* rough guide is that a value of `0` corresponds to no precipitation, `0.002` corresponds to very light precipitation, `0.017` corresponds to light precipitation, `0.1` corresponds to moderate precipitation, and `0.4` corresponds to heavy precipitation.
+    /// The intensity of precipitation occuring at the given time. This value is *conditional on probability* (that is, assuming any precipitation falls at all) for `minutely` `DataPoint`s, and unconditional otherwise.
     public let precipitationIntensity: Float?
 
-    /// Maximum expected intensity of precipitation on the given day in inches of liquid water per hour. Only defined on `Forecast`'s `daily` `DataPoint`s.
+    /// The maximum value of `precipitationIntensity` during a given day. Only defined on `Forecast`'s `daily` `DataPoint`s.
     public let precipitationIntensityMax: Float?
 
-    /// Time at which the maximum expected intensity of precipitation will occur. Only defined on `Forecast`'s `daily` `DataPoint`s.
+    /// The time at which `precipitationIntensityMax` occurs during a given day. Only defined on `Forecast`'s `daily` `DataPoint`s.
     public let precipitationIntensityMaxTime: Date?
 
-    /// Value between `0` and `1` (inclusive) representing the probability of precipitation occurring at the given time.
+    /// The probability of precipitation occurring, between `0` and `1`, inclusive.
     public let precipitationProbability: Float?
 
-    /// Type of precipitation occurring at the given time. If `precipIntensity` is `0`, then this will be `nil`.
+    /// The type of precipitation occurring at the given time. If `precipIntensity` is `0`, then this will be `nil`.
     public let precipitationType: Precipitation?
 
-    /// The amount of snowfall accumulation expected to occur on the given day, in inches. This will be `nil` if no accumulation is expected. Only defined on `Forecast`'s `hourly` and `daily` `DataPoint`s.
+    /// The amount of snowfall accumulation expected to occur. This will be `nil` if no accumulation is expected. Only defined on `Forecast`'s `hourly` and `daily` `DataPoint`s.
     public let precipitationAccumulation: Float?
 
-    /// The temperature at the given time in degrees Fahrenheit. Not defined on `Forecast`'s `daily` `DataPoint`s.
+    /// The air temperature. Not defined on `Forecast`'s `minutely` `DataPoint`s.
     public let temperature: Float?
 
     /// The overnight low temperature. Only defined on `Forecast`'s `daily` `DataPoint`s.
@@ -68,7 +68,7 @@ public struct DataPoint {
     /// The time at which the daytime high temperature occurs. Only defined on `Forecast`'s `daily` `DataPoint`s.
     public let temperatureHighTime: Date?
 
-    /// The apparent or "feels like" temperature at the given time in degrees Fahrenheit. Not defined on `Forecast`'s `daily` `DataPoint`s.
+    /// The apparent or "feels like" temperature. Not defined on `Forecast`'s `daily` `DataPoint`s.
     public let apparentTemperature: Float?
 
     /// The overnight low apparent temperature. Only defined on `Forecast`'s `daily` `DataPoint`s.
@@ -83,25 +83,28 @@ public struct DataPoint {
     /// The time at which the daytime high apparent temperature occurs. Only defined on `Forecast`'s `daily` `DataPoint`s.
     public let apparentTemperatureHighTime: Date?
 
-    /// The dew point at the given time in degrees Fahrenheit.
+    /// The dew point at the given time.
     public let dewPoint: Float?
 
-    /// The wind speed at the given time in miles per hour.
+    /// The wind gust speed.
+    public let windGust: Float?
+    
+    /// The wind speed at the given time.
     public let windSpeed: Float?
 
-    /// The direction that the wind is coming from in degrees, with true north at 0º and progressing clockwise. If `windSpeed` is `0`, then this will be `nil`.
+    /// The direction that the wind is coming *from* in degrees, with true north at 0º and progressing clockwise. If `windSpeed` is `0`, then this will be `nil`.
     public let windBearing: Float?
 
-    /// Value between `0` and `1` (inclusive) representing the percentage of sky occluded by clouds. A value of `0` corresponds to a clear sky, `0.4` corresponds to scattered clouds, `0.75` correspond to broken cloud cover, and `1` corresponds to completely overcast skies.
+    /// The percentage of sky occluded by clouds, between `0` and `1`, inclusive.
     public let cloudCover: Float?
 
-    /// Value between `0` and `1` (inclusive) representing the relative humidity.
+    /// The relative humidity, between `0` and `1`, inclusive.
     public let humidity: Float?
 
-    /// The sea-level air pressure in millibars.
+    /// The sea-level air pressure.
     public let pressure: Float?
 
-    /// The average visibility in miles, capped at `10`.
+    /// The average visibility, capped at 10 miles.
     public let visibility: Float?
 
     /// The columnar density of total atomspheric ozone at the given time in Dobson units.
@@ -110,7 +113,7 @@ public struct DataPoint {
     /// The UV index.
     public let uvIndex: Float?
 
-    // The time at which the maximum UV index occurs during the given day.
+    /// The time at which the maximum UV index occurs during the given day. Only defined on `Forecast`'s `daily` `DataPoint`s.
     public let uvIndexTime: Date?
 
     /// Creates a new `DataPoint` from a JSON object.
@@ -180,6 +183,7 @@ public struct DataPoint {
             apparentTemperatureHighTime = nil
         }
         dewPoint = json["dewPoint"] as? Float
+        windGust = json["windGust"] as? Float
         windSpeed = json["windSpeed"] as? Float
         windBearing = json["windBearing"] as? Float
         cloudCover = json["cloudCover"] as? Float