From d15b0912fe092e3256fc03e48e5ecea1bce7b33a Mon Sep 17 00:00:00 2001
From: Katharine Hyatt <kshyatt@users.noreply.github.com>
Date: Mon, 13 Aug 2018 09:16:08 -0400
Subject: [PATCH] Doc IndexLinear and IndexCartesian (#28476)

* Doc IndexLinear and IndexCartesian
---
 base/cartesian.jl      |  2 +-
 base/indices.jl        | 33 +++++++++++++++++++++++++++++----
 base/iterators.jl      |  6 +++---
 doc/src/base/arrays.md |  2 ++
 4 files changed, 35 insertions(+), 8 deletions(-)

diff --git a/base/cartesian.jl b/base/cartesian.jl
index 526cff67bd706..865b766664708 100644
--- a/base/cartesian.jl
+++ b/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...)
diff --git a/base/indices.jl b/base/indices.jl
index adec164f080b5..800280c90f57e 100644
--- a/base/indices.jl
+++ b/base/indices.jl
@@ -13,7 +13,32 @@ 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
 
 """
@@ -21,14 +46,14 @@ struct IndexCartesian <: IndexStyle end
     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
diff --git a/base/iterators.jl b/base/iterators.jl
index 396b1744482f7..1564ffa1be9a1 100644
--- a/base/iterators.jl
+++ b/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.
diff --git a/doc/src/base/arrays.md b/doc/src/base/arrays.md
index 521cbc2d3dea8..260649a3a36cf 100644
--- a/doc/src/base/arrays.md
+++ b/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