Abstract Interfaces (Dicts, IOs, etc) Going to be Documented?

Are interfaces to AbstractDicts, IOs, and other things planned to be documented in the future (similar to how AbstractArrays, iterators, etc) or somewhere that I’ve completely missed? I’ve found docstrings that give hints to what kind of support one should add for these but I haven’t found a dedicated space that expounds on this.

10 Likes

Basically, this came up again in https://stackoverflow.com/questions/58779529/creating-custom-types-in-julia

The best way to get an interface documented is to either open an issue (if one does not exist), or if the API is otherwise mature, proceed to a PR.

I am not sure that a subsection in Interfaces is warranted for all abstract types. In most cases a docstring for AbstractSomething could be enough.

1 Like

Thinking about this a bit more, I think that in Base (and similarly, most complex Julia codebases) there is a spectrum between abstract types

  1. serving as mere implementation details (eg a way of organizing dispatch), and

  2. interfaces to be extended.

Eg AbstractCartesianIndex is a clear example of (1) (it says so in its comment), while AbstractArray is (2). I suspect a lot of other types are in between — perhaps not with the original intent, but given how the code evolved. It would be better to clarify this first.