Merge pull request #20712 from JuliaLang/teh/doc_cartesian

Add CartesianIndex & CartesianRange docstrings, misc doc improvements

Author: timholy

base/multidimensional.jl

@@ -12,7 +12,22 @@ module IteratorsMD
 
     export CartesianIndex, CartesianRange
 
-    # CartesianIndex
+    """
+        CartesianIndex(i, j, k...)   -> I
+        CartesianIndex((i, j, k...)) -> I
+
+    Create a multidimensional index `I`, which can be used for
+    indexing a multidimensional array `A`.  In particular, `A[I]` is
+    equivalent to `A[i,j,k...]`.  One can freely mix integer and
+    `CartesianIndex` indices; for example, `A[Ipre, i, Ipost]` (where
+    `Ipre` and `Ipost` are `CartesianIndex` indices and `i` is an
+    `Int`) can be a useful expression when writing algorithms that
+    work along a single dimension of an array of arbitrary
+    dimensionality.
+
+    A `CartesianIndex` is sometimes produced by [`eachindex`](@ref), and
+    always when iterating with an explicit [`CartesianRange`](@ref).
+    """
     struct CartesianIndex{N} <: AbstractCartesianIndex{N}
         I::NTuple{N,Int}
         CartesianIndex{N}(index::NTuple{N,Integer}) where {N} = new(index)
@@ -77,6 +92,25 @@ module IteratorsMD
     icmp(a, b) = ifelse(isless(a,b), 1, ifelse(a==b, 0, -1))
 
     # Iteration
+    """
+        CartesianRange(Istart::CartesianIndex, Istop::CartesianIndex) -> R
+        CartesianRange(sz::Dims) -> R
+        CartesianRange(istart:istop, jstart:jstop, ...) -> R
+
+    Define a region `R` spanning a multidimensional rectangular range
+    of integer indices. These are most commonly encountered in the
+    context of iteration, where `for I in R ... end` will return
+    [`CartesianIndex`](@ref) indices `I` equivalent to the nested loops
+
+        for j = jstart:jstop
+            for i = istart:istop
+                ...
+            end
+        end
+
+    Consequently these can be useful for writing algorithms that
+    work in arbitrary dimensions.
+    """
     struct CartesianRange{I<:CartesianIndex}
         start::I
         stop::I

base/reshapedarray.jl

@@ -37,15 +37,19 @@ end
 length(R::ReshapedArrayIterator) = length(R.iter)
 
 """
-    reshape(A, dims...)
-    reshape(A, dims)
-
-Return an array with the same data as the given array, but with different dimensions.
-
-The new dimensions may be specified either as a list of arguments or as a shape
-tuple. At most one dimension may be specified with a `:`, in which case its
-length is computed such that its product with all the specified dimensions is
-equal to the length of the original array A.
+    reshape(A, dims...) -> R
+    reshape(A, dims) -> R
+
+Return an array `R` with the same data as `A`, but with different
+dimension sizes or number of dimensions. The two arrays share the same
+underlying data, so that setting elements of `R` alters the values of
+`A` and vice versa.
+
+The new dimensions may be specified either as a list of arguments or
+as a shape tuple. At most one dimension may be specified with a `:`,
+in which case its length is computed such that its product with all
+the specified dimensions is equal to the length of the original array
+`A`. The total number of elements must not change.
 
 ```jldoctest
 julia> A = collect(1:16)

doc/src/stdlib/arrays.md

@@ -32,13 +32,13 @@ Base.trues
 Base.falses
 Base.fill
 Base.fill!
-Base.reshape
 Base.similar(::AbstractArray)
 Base.similar(::Any, ::Tuple)
-Base.reinterpret
 Base.eye
 Base.linspace
 Base.logspace
+Base.Random.randsubseq
+Base.Random.randsubseq!
 ```
 
 ## Broadcast and vectorization
@@ -56,20 +56,38 @@ Base.Broadcast.broadcast_getindex
 Base.Broadcast.broadcast_setindex!
 ```
 
-## Indexing, Assignment, and Concatenation
+## Indexing and assignment
 
 ```@docs
 Base.getindex(::AbstractArray, ::Any...)
+Base.setindex!(::AbstractArray, ::Any, ::Any...)
+Base.isassigned
+Base.Colon
+Base.CartesianIndex
+Base.CartesianRange
+Base.to_indices
+Base.checkbounds
+Base.checkindex
+```
+
+## Views (SubArrays and other view types)
+
+```@docs
 Base.view
 Base.@view
 Base.@views
-Base.to_indices
-Base.Colon
 Base.parent
 Base.parentindexes
 Base.slicedim
-Base.setindex!(::AbstractArray, ::Any, ::Any...)
-Base.isassigned
+Base.reinterpret
+Base.reshape
+Base.squeeze
+Base.vec
+```
+
+## Concatenation and permutation
+
+```@docs
 Base.cat
 Base.vcat
 Base.hcat
@@ -98,13 +116,7 @@ Base.findprev(::Any, ::Any, ::Integer)
 Base.permutedims
 Base.permutedims!
 Base.PermutedDimsArray
-Base.squeeze
-Base.vec
 Base.promote_shape
-Base.checkbounds
-Base.checkindex
-Base.Random.randsubseq
-Base.Random.randsubseq!
 ```
 
 ## Array functions