confusing docs for `range`

[ssfrr]

As of 1.1 the docs for range say:

    range(start[, stop]; length, stop, step=1)

Given a starting value, construct a range either by length or from start
to stop, optionally with a given step (defaults to 1, a UnitRange). One of
length or stop is required. If length, stop, and step are all specified, they
must agree.

Based on the docs it seems like range(1, 5) should be valid, but it throws the error that "at least one of length or step must be specified".

From the doc header it looks like step is specified by default, so it seems weird that range(1, 5) would be different from range(1, 5; step=1). Also it makes it look like stop can be specified either positionally or by keyword, so I'd think specifying positionally would satisfy that "One of length or stop is required".

Based on the discussion in #28708 this seems like the intended behavior, but it seems like allowing range(a, b) would be consistent with the docs and somewhat simpler as just meaning the same thing as a:b.

This confusion popped up in a recent PR in DSP.jl.

(@galenlynch)

[galenlynch]

Also this is a bummer, even if I do understand why it's the case:

julia> typeof(1:2)
UnitRange{Int64}

julia> typeof(range(1, 2, step = 1))
StepRange{Int64,Int64}

In contrast, in Julia 0.7 (and 1.0?):

julia> typeof(range(1, 2))
┌ Warning: `range(start, length)` is deprecated, use `range(start, length=length)` instead.
│   caller = top-level scope at none:0
└ @ Core none:0
UnitRange{Int64}

This can make a big difference when trying to construct arrays with custom axes with packages like OffsetArrays.jl.

[sostock]

As of Julia 1.7, range(1, 5) is valid and equivalent to 1:5. The docstring has also been revised.