Clarify axes return type. (#37852)

1. document that the indices cannot be arbitrary unit ranges (eg of
unit, dates, etc).

2. add a cautionary note about custom indexes (ie current OffsetArrays
behavior)

Author: tpapp

base/abstractarray.jl

@@ -45,12 +45,25 @@ Return the valid range of indices for array `A` along dimension `d`.
 See also [`size`](@ref), and the manual chapter on [arrays with custom indices](@ref man-custom-indices).
 
 # Examples
+
 ```jldoctest
 julia> A = fill(1, (5,6,7));
 
 julia> axes(A, 2)
 Base.OneTo(6)
 ```
+
+# Usage note
+
+Each of the indices has to be an `AbstractUnitRange{<:Integer}`, but at the same time can be
+a type that uses custom indices. So, for example, if you need a subset, use generalized
+indexing constructs like `begin`/`end` or [`firstindex`](@ref)/[`lastindex`](@ref):
+
+```julia
+ix = axes(v, 1)
+ix[2:end]          # will work for eg Vector, but may fail in general
+ix[(begin+1):end]  # works for generalized indexes
+```
 """
 function axes(A::AbstractArray{T,N}, d) where {T,N}
     @_inline_meta
@@ -63,6 +76,7 @@ end
 Return the tuple of valid indices for array `A`.
 
 # Examples
+
 ```jldoctest
 julia> A = fill(1, (5,6,7));
 

doc/src/devdocs/offset-arrays.md

@@ -56,7 +56,7 @@ the cause try running julia with the option `--check-bounds=yes`.)
 
 ### Using `axes` for bounds checks and loop iteration
 
-`axes(A)` (reminiscent of `size(A)`) returns a tuple of `AbstractUnitRange` objects, specifying
+`axes(A)` (reminiscent of `size(A)`) returns a tuple of `AbstractUnitRange{<:Integer}` objects, specifying
 the range of valid indices along each dimension of `A`.  When `A` has unconventional indexing,
 the ranges may not start at 1.  If you just want the range for a particular dimension `d`, there
 is `axes(A, d)`.

doc/src/manual/interfaces.md

@@ -234,7 +234,7 @@ ourselves, we can officially define it as a subtype of an [`AbstractArray`](@ref
 | `similar(A, dims::Dims)`                        | `similar(A, eltype(A), dims)`          | Return a mutable array with the same element type and size *dims*                     |
 | `similar(A, ::Type{S}, dims::Dims)`             | `Array{S}(undef, dims)`                | Return a mutable array with the specified element type and size                       |
 | **Non-traditional indices**                     | **Default definition**                 | **Brief description**                                                                 |
-| `axes(A)`                                    | `map(OneTo, size(A))`                  | Return the `AbstractUnitRange` of valid indices                                       |
+| `axes(A)`                                    | `map(OneTo, size(A))`                  | Return the a tuple of `AbstractUnitRange{<:Integer}` of valid indices                    |
 | `similar(A, ::Type{S}, inds)`              | `similar(A, S, Base.to_shape(inds))`   | Return a mutable array with the specified indices `inds` (see below)                  |
 | `similar(T::Union{Type,Function}, inds)`   | `T(Base.to_shape(inds))`               | Return an array similar to `T` with the specified indices `inds` (see below)          |