Add function docstrings and key word parameter support

README.md

@@ -6,6 +6,8 @@ A Julia wrapper for the Dark Sky weather data API.
 
 [![coveralls](https://coveralls.io/repos/ellisvalentiner/DarkSky.jl/badge.svg?branch=master&service=github)](https://coveralls.io/github/ellisvalentiner/DarkSky.jl?branch=master) [![codecov](https://codecov.io/gh/ellisvalentiner/DarkSky.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/ellisvalentiner/DarkSky.jl)
 
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://ellisvalentiner.github.io/DarkSky.jl/stable) [![](https://img.shields.io/badge/docs-latest-blue.svg)](https://ellisvalentiner.github.io/DarkSky.jl/latest)
+
 ## Overview
 
 This package is a wrapper for the Dark Sky API.

REQUIRE

@@ -1,3 +1,4 @@
 julia 0.6
+ArgCheck
 HTTP
 JSON

docs/src/index.md

@@ -6,6 +6,8 @@ A Julia wrapper for the Dark Sky weather data API.
 
 [![coveralls](https://coveralls.io/repos/ellisvalentiner/DarkSky.jl/badge.svg?branch=master&service=github)](https://coveralls.io/github/ellisvalentiner/DarkSky.jl?branch=master) [![codecov](https://codecov.io/gh/ellisvalentiner/DarkSky.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/ellisvalentiner/DarkSky.jl)
 
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://ellisvalentiner.github.io/DarkSky.jl/stable) [![](https://img.shields.io/badge/docs-latest-blue.svg)](https://ellisvalentiner.github.io/DarkSky.jl/latest)
+
 ## Overview
 
 This package is a wrapper for the Dark Sky API.

src/DarkSky.jl

@@ -2,11 +2,17 @@ VERSION >= v"0.6.0" && __precompile__()
 
 module DarkSky
 
+using ArgCheck
 using HTTP
 using JSON
 using Base.Dates
 
 Optional{T} = Union{T, Void}
+const SUPPORTED_LANGS = ["ar", "az", "be", "bg", "bs", "ca", "cs", "da", "de", "el", "en", "es",
+                         "et", "fi", "fr", "hr", "hu", "id", "is", "it", "ja", "ka", "kw", "nb",
+                         "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sr", "sv", "tet", "tr", "uk",
+                         "x-pig-latin", "zh", "zh-tw"]
+const SUPPORTED_UNITS = ["auto", "ca", "uk2", "us", "si"]
 
 struct DarkSkyResponse
     latitude::Float64
@@ -30,12 +36,49 @@ function _get_json(url::String, verbose::Bool)
 end
 
 """
-    forecast(latitude::Float64, longitude::Float64; verbose::Bool=true)
+    forecast(latitude::Float64, longitude::Float64; verbose::Bool=true, kwargs...)
 
 Make a "Forecast Request", returns the current weather forecast for the next week.
+
+    forecast(latitude::Float64, longitude::Float64, time::DateTime; verbose::Bool=true, kwargs...)
+
+Make a "Time Machine Request", returns the observed or forecast weather conditions for a date in
+the past or future.
+
+# Keyword Arguments
+- `latitude`: the latitude of a location (in decimal degrees). Positive is north, negative is south.
+- `longitude`: the longitude of a location (in decimal degrees). Positive is east, negative is west.
+- `verbose`: whether to display the HTTP request verbosely.
+- `exclude`: exclude some number of data blocks from the API response  (see the [Dark Sky API documentation](https://darksky.net/dev/docs#forecast-request)). This is useful for reducing latency and saving cache space.
+- `extend`: when present, return hour-by-hour data for the next 168 hours, instead of the next 48.
+- `lang`: return summary properties in the desired language (see the [Dark Sky API documentation](https://darksky.net/dev/docs#forecast-request)).
+- `units`: return weather conditions in the requested units (see the [Dark Sky API documentation](https://darksky.net/dev/docs#forecast-request)).
 """
-forecast(latitude::Float64, longitude::Float64; verbose::Bool=true) = _get_json("https://api.darksky.net/forecast/$(ENV["DARKSKY_API_KEY"])/$latitude,$longitude", verbose)
-forecast(latitude::Float64, longitude::Float64, time::DateTime; verbose::Bool=true) = _get_json("https://api.darksky.net/forecast/$(ENV["DARKSKY_API_KEY"])/$latitude,$longitude,$time", verbose)
+function forecast(latitude::Float64, longitude::Float64; verbose::Bool=true,
+                  exclude::Optional{Array{String}}=nothing, extend::Optional{String}=nothing,
+                  lang::String="en", units::String="us")
+    @argcheck in(lang, SUPPORTED_LANGS)
+    @argcheck in(units, SUPPORTED_UNITS)
+    url = "https://api.darksky.net/forecast/$(ENV["DARKSKY_API_KEY"])/$latitude,$longitude?lang=$lang,units=$units"
+    if !(exclude === nothing)
+        url = "$url,exclude=$(join(exclude, ","))"
+    end
+    if !(extend === nothing)
+        url = "$url,extend=$extend"
+    end
+    _get_json(url, verbose)
+end
+function forecast(latitude::Float64, longitude::Float64, time::DateTime; verbose::Bool=true,
+                  extend::Optional{String}=nothing, lang::String="en", units::String="us")
+    @argcheck in(lang, SUPPORTED_LANGS)
+    @argcheck in(units, SUPPORTED_UNITS)
+    url = "https://api.darksky.net/forecast/$(ENV["DARKSKY_API_KEY"])/$latitude,$longitude?lang=$lang,units=$units"
+    if !(extend === nothing)
+      url = "$url,extend=$extend"
+    end
+    _get_json(url, verbose)
+end
+
 export forecast
 
 end # module