Unclear documentation of `checkbounds(::Bool, ...)`

[eschnett]

This function has the documentation

  checkbounds(::Type{Bool}, dimlength::Integer, index)

  Return a Bool describing if the given index is within the bounds of the
  given dimension length. Custom types that would like to behave as indices
  for all arrays can extend this method in order to provide a specialized
  bounds checking implementation.

I don't understand the term "dimension length".

I also don't understand how this helps defining a new type that can be used as index for all arrays -- wouldn't that require re-defining all array types' getindex functions?

Furthermore, there seems to be a function function checkbounds(::Type{Bool}, sz::Dims, I...) that is exported, but not documented.

[mbauman]

A dimension length is like size(A, 1). I'm definitely open to better terminology here. It's just checking to see if all(1 .<= index .<= dimlength). You're right, it doesn't allow any index type, but it does allow custom Reals and AbstractArrays to change the behavior. It's notably used by DataArrays and NullableArrays to deal with missing data.

Note that this needs get re-worked in order to support cartesian indices: #15449 (comment).

[eschnett]

"index range"? "size of dimension"?

Would this work?

  checkbounds(::Type{Bool}, maxsize::Integer, index)

  Return a Bool describing whether the given index is in the range `1:maxsize`.
  Note that `index` can not only be an integer, but also e.g. a floating-point number,
  a range, or a placeholder like `:` (Colon).

  Custom types that would like to behave as indices
  for all arrays can extend this method in order to provide a specialized
  bounds checking implementation.

[mbauman]

Sure, that'd be fine, but I don't think I'd call out floating point indexes.

[kshyatt]

The docstring for this function seems to have changed substantially so I'm going to close. Feel free to reopen if it's still unclear.