Document the generic functions nextind() and prevind()

[JamesWrigley]

While going through the comments on #52625 I noticed that the array methods for nextind() and prevind() didn't have docstrings, only the string method.

Fixes #42084.

[jishnub]

Are these methods useful for arrays? Typically, axes for arrays are AbstractUnitRanges, so indices should always be spaced by one

[JamesWrigley]

I think they're mostly useful for writing generic code that could take in arbitrary indices. e.g. with something like findnext(array, start) you'd want to allow start being an integer or CartesianIndex.

[inkydragon]

LGTM

[barucden]

The argument type should not be restricted to AbstractArrays. We have similar methods for tuple arguments too. I left a few comments in that direction. The comments also apply for the documentation of nextind.

Please, add Fixes #42084 to the PR description.

[barucden]

Suggested change

	prevind(::AbstractArray, i)
	prevind(A, i)

[inkydragon]

Since there are prevind functions for other types of input, perhaps preserving the type signature is acceptable?

julia> methods(prevind)
# 8 methods for generic function "prevind" from Base:
 [1] prevind(s::AbstractString, i::Int64, n::Int64)
     @ strings\basic.jl:499
 [2] prevind(s::AbstractString, i::Integer, n::Integer)
     @ strings\basic.jl:495
 [3] prevind(s::AbstractString, i::Int64)
     @ strings\basic.jl:497
 [4] prevind(s::AbstractString, i::Integer)
     @ strings\basic.jl:496
 [5] prevind(a::AbstractArray{<:Any, N}, i::CartesianIndex{N}) where N
     @ Base.IteratorsMD multidimensional.jl:155
 [6] prevind(::AbstractArray, i::Integer)
     @ abstractarray.jl:212
 [7] prevind(t::Tuple, i::Integer)
     @ tuple.jl:77
 [8] prevind(t::NamedTuple, i::Integer)
     @ namedtuple.jl:180

[barucden]

Right now, we do not have any documentation for prevind(A, i) as reported in #42084. This PR provided documentation for the AbstractArray methods, but I meant to point out that, in order to fix the issue, this PR should introduce a single description that applies to any prevind(A, i) method no matter what A (and i) exactly are. In that sense, I would say the type signature should not be included.

We also have, e.g., the dot function documented as dot(x, y) (no type signatures) even though there are many two-argument methods of different argument types.

(...and the same for nextind)

[inkydragon]

JuliaHub's search results show that two-parameter prevind definition is more common.
Also, most prevind definitions are for String types.

Perhaps most people assume that for inputs of type Array, the spacing of the indexes is one by default, so there is no need to use a function to get the previous index.

This PR provided documentation for the AbstractArray methods, but I meant to point out that, in order to fix the issue

Yes, I think this pr only adds documentation to function with input type AbstractArray, and there are other types of input documentation indeed, so maybe it can't just be closed yet #42084 .

I have no preference for this at the moment, so please feel free to accept suggestions for changes or not. @JamesWrigley

[barucden]

Quickly skimmimg through the juliahub results, it seems that the methods still do the same thing: get the index that is right before a given index in some collection (maybe string).

We never provided any documentation so packages could implement the method in any way, I guess. But I believe we should be able to provide a generic description for the method. We were able to do that for firstindex, eachindex, etc.

[inkydragon]

My idea is to let us add documentation for specific functions first.

If we want to recommend that people extend these functions (interfaces), in a uniform way, then the more recommended way would be to add another subsection to the corresponding manual that describes these functions and tells people how to implement them for custom data types.

More improvements could be made in follow up pr's.
I tend to make only a minimal amount of changes in each pr so that it's easy for people to review and merge quickly.

[LilithHafner]

I think it is a good idea to document the most generic method before or even instead of documenting more specific methods. When documenting individual methods, we get more verbose documentation and still someone may still not know how to use this function in generic code where they do not know the collection type they are working with, nor how to implement the function on a custom type. From the manual

In general, only the most generic method should be documented, or even the function itself (i.e. the object created without any methods by function bar end). Specific methods should only be documented if their behaviour differs from the more generic ones. In any case, they should not repeat the information provided elsewhere.

I agree with @barucden that this PR's content (with minor modification) should be applied to the generic case.

[JamesWrigley]

Ok, I made it generic in 648b68d.

[JamesWrigley]

(I assume you want to take over the PR @inkydragon so I'll let you respond to the other review comments)

[barucden]

I think that all concerns have been addressed. In its current state, this PR closes #42084 in my opinion.

[LilithHafner]

I reverted the accidental removal of a comment and moved the docstrings from applying to the specific AbstractArray methods to applying to generic functions. To do this I had to move them to the base/tuple.jl file because that is where the first methods are defined.