Document requirements for the refpool return value (#24)

Without supporting `keys` and related functions, `refpool` is useless.
In practice, experience from DataFrames and Arrow shows that the object
should be iterable (otherwise one would need to collect it to a vector
before passing it to many functions) and support `eltype`.

Also document that equality refers to `isequal` and that the object is supposed to be
of the same type as the original, which was previously implied by
"is the appropriate *original* value" without being explicit.

Author: nalimilan

src/DataAPI.jl

@@ -52,11 +52,17 @@ refvalue(A::AbstractArray, x) = x
 
 Whenever available, return an indexable object `pool` such that, given the *original* array `A` and
 a "ref value" `x` taken from `refarray(A)`, `pool[x]` is the appropriate *original* value. Return
-`nothing` if such object is not available. If `refpool(A)` is not `nothing`, then
-`refpool(A)[refarray(A)[I...]]` must be equal to `A[I...]`.
+`nothing` if such object is not available.
 
 By default, `refpool(A)` returns `nothing`.
 
+If `refpool(A)` is not `nothing`, then `refpool(A)[refarray(A)[I...]]`
+must be equal to (according to `isequal`) and of the same type as `A[I...]`,
+and the object returned by `refpool(A)` must implement the iteration and
+indexing interfaces as well as the `length`, `eachindex`, `keys`, `values`, `pairs`,
+`firstindex`, `lastindex`, and `eltype` functions
+in accordance with the `AbstractArray` interface.
+
 This generic function is owned by DataAPI.jl itself, which is the sole provider of the
 default definition.
 """