Doc IndexLinear and IndexCartesian (#28476)

* Doc IndexLinear and IndexCartesian

Author: kshyatt

base/cartesian.jl

@@ -32,7 +32,7 @@ would generate:
         end
     end
 
-If you want just a post-expression, supply `nothing` for the pre-expression. Using
+If you want just a post-expression, supply [`nothing`](@ref) for the pre-expression. Using
 parentheses and semicolons, you can supply multi-statement expressions.
 """
 macro nloops(N, itersym, rangeexpr, args...)

base/indices.jl

@@ -13,22 +13,47 @@ Indices{N} = NTuple{N,AbstractUnitRange}
 ## Traits for array types ##
 
 abstract type IndexStyle end
+"""
+    IndexLinear()
+
+Subtype of [`IndexStyle`](@ref) used to describe arrays which
+are optimally indexed by one linear index.
+
+A linear indexing style uses one integer to describe the position in the array
+(even if it's a multidimensional array) and column-major
+ordering is used to access the elements. For example,
+if `A` were a `(2, 3)` custom matrix type with linear indexing,
+and we referenced `A[5]` (using linear style), this would
+be equivalent to referencing `A[1, 3]` (since `2*1 + 3 = 5`).
+See also [`IndexCartesian`](@ref).
+"""
 struct IndexLinear <: IndexStyle end
+"""
+    IndexCartesian()
+
+Subtype of [`IndexStyle`](@ref) used to describe arrays which
+are optimally indexed by a Cartesian index.
+
+A cartesian indexing style uses multiple integers/indices to describe the position in the array.
+For example, if `A` were a `(2, 3, 4)` custom matrix type with cartesian indexing,
+we could reference `A[2, 1, 3]` and Julia would automatically convert this into the
+correct location in the underlying memory. See also [`IndexLinear`](@ref).
+"""
 struct IndexCartesian <: IndexStyle end
 
 """
     IndexStyle(A)
     IndexStyle(typeof(A))
 
 `IndexStyle` specifies the "native indexing style" for array `A`. When
-you define a new `AbstractArray` type, you can choose to implement
-either linear indexing or cartesian indexing.  If you decide to
-implement linear indexing, then you must set this trait for your array
+you define a new [`AbstractArray`](@ref) type, you can choose to implement
+either linear indexing (with [`IndexLinear`](@ref)) or cartesian indexing.
+If you decide to implement linear indexing, then you must set this trait for your array
 type:
 
     Base.IndexStyle(::Type{<:MyArray}) = IndexLinear()
 
-The default is `IndexCartesian()`.
+The default is [`IndexCartesian()`](@ref).
 
 Julia's internal indexing machinery will automatically (and invisibly)
 convert all indexing operations into the preferred style. This allows users

base/iterators.jl

@@ -181,9 +181,9 @@ Also similar to `enumerate(A)`, except `i` will be a valid index
 for `A`, while `enumerate` always counts from 1 regardless of the indices
 of `A`.
 
-Specifying `IndexLinear()` ensures that `i` will be an integer;
-specifying `IndexCartesian()` ensures that `i` will be a
-`CartesianIndex`; specifying `IndexStyle(A)` chooses whichever has
+Specifying [`IndexLinear()`](@ref) ensures that `i` will be an integer;
+specifying [`IndexCartesian()`](@ref) ensures that `i` will be a
+[`CartesianIndex`](@ref); specifying `IndexStyle(A)` chooses whichever has
 been defined as the native indexing style for array `A`.
 
 Mutation of the bounds of the underlying array will invalidate this iterator.

doc/src/base/arrays.md

@@ -53,6 +53,8 @@ Base.axes(::AbstractArray, ::Any)
 Base.length(::AbstractArray)
 Base.eachindex
 Base.IndexStyle
+Base.IndexLinear
+Base.IndexCartesian
 Base.conj!
 Base.stride
 Base.strides