Taking collection interfaces seriously

[CameronBieganek]

This will probably get closed as a duplicate, but I think it is high time that we provide actual interface definitions for the various collection categories listed on the "Collections and Data Structures" page of the manual. That page hints at interfaces for the various categories, but does not provide a clear guide to which methods are required and which methods are optional in order to implement the various interfaces. (Plus, that page includes docstrings for a bunch of functions that most likely do not need to be implemented by new types.)

Here is a list of collection interfaces from that page that need better documentation on the interface requirements:

• General Collections
• Indexable Collections
• Dictionaries (AbstractDict)
• Set-Like Collections (AbstractSet)
• Dequeues

See also #34677 and #25941. And also #28784 for documentation of the AbstractString interface.

[rafaqz]

This should be kept open rather than distributed across multiple smaller issues, as that hasn't seemed to work so far.

For reference I've started fleshing out interface tests for some of these at https://github.com/rafaqz/Interfaces.jl/tree/main/BaseInterfaces
There is some interest in getting BaseInterfaces.jl registered so people can test their objects against these interfaces (rafaqz/Interfaces.jl#48) so it would be good to collaborate on these things.

Interfaces.jl syntax with descriptions connected to test functions makes the interface very clear, and will let us test their assertions against all base objects to see if they actually hold. That workflow is already set up and working with the current tests.

AbstractSet is well tested and documented because of the @oxinabox issue, AbstractArray and iteration because of the available docs, but the others much less so.

Unfortunately Base breaks its own documented interfaces often enough that it's still not totally straightforward, like LogicalIndex not defining getindex as an AbstractArray. But we can at least blacklist those objects in some kind of "table of shame" when its all done explicitly.

[nsajko]

xref #55129, making setindex public

current discussion: https://discourse.julialang.org/t/making-setindex-public-how-to-document-it-rethinking-the-collections-docs/117419

[putianyi889]

I'm into having a table to list the methods the types support, something similar to https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/#Special-matrices