Explicitly document keyword arguments to HTTP.URI

[CameronBieganek]

Julia 1.4.0
HTTP.jl 0.8.14
MbedTLS.jl 1.0.1

The use of etc... in the documentation for HTTP.URI is pretty ambiguous. In particular, the query keyword is not well documented. One could reasonably assume the following should work:

julia> HTTP.URI(scheme="https", host="julialang.org", path="/foo/bar", query="id"=>1234)
ERROR: BoundsError: attempt to access Int64
  at index [2]
Stacktrace:
 [1] indexed_iterate(::Int64, ::Int64, ::Nothing) at ./tuple.jl:90
 [2] (::HTTP.URIs.var"#16#17")(::Int64) at ./none:0
 [3] iterate at ./generator.jl:47 [inlined]
 [4] join(::Base.GenericIOBuffer{Array{UInt8,1}}, ::Base.Generator{Pair{String,Int64},HTTP.URIs.var"#16#17"}, ::String) at ./strings/io.jl:296
 [5] sprint(::Function, ::Base.Generator{Pair{String,Int64},HTTP.URIs.var"#16#17"}, ::Vararg{Any,N} where N; context::Nothing, sizehint::Int64) at ./strings/io.jl:105
 [6] sprint at ./strings/io.jl:101 [inlined]
 [7] join at ./strings/io.jl:301 [inlined]
 [8] escapeuri at /Users/bieganek/.julia/packages/HTTP/GkPBm/src/URIs.jl:320 [inlined]
 [9] merge(::HTTP.URIs.URI; scheme::String, userinfo::SubString{String}, host::String, port::SubString{String}, path::String, query::Pair{String,Int64}, fragment::SubString{String}) at /Users/bieganek/.julia/packages/HTTP/GkPBm/src/URIs.jl:87
 [10] #URI#3 at /Users/bieganek/.julia/packages/HTTP/GkPBm/src/URIs.jl:66 [inlined]
 [11] top-level scope at REPL[22]:1

It turns out the correct syntax is either

julia> HTTP.URI(scheme="https", host="julialang.org", path="/foo/bar", query=["id"=>1234])
HTTP.URI("https://julialang.org/foo/bar?id=1234")

or

julia> HTTP.URI(scheme="https", host="julialang.org", path="/foo/bar", query=Dict("id"=>1234))
HTTP.URI("https://julialang.org/foo/bar?id=1234")

Heck, I even tried this:

julia> HTTP.URI(; scheme="https", host="julialang.org", path="/foo/bar", "id"=>1234)
ERROR: TypeError: in Type, in parameter, expected Type, got Tuple{String}
Stacktrace:
 [1] top-level scope at REPL[28]:1

though I was pretty sure it wouldn't work...

[quinnj]

PR #73 documents URI(; kwargs...) and URI(uri::URI; kwargs...), including component removal and query examples. It will close this issue when merged.

[investigated by codex; reviewed by quinnj]