Docstring and skeleton updates

[lkdvos]

I went through the code and started adding some docs since I managed to get myself a bit confused about the whole code organization. I left some TODO-tagged questions in the code for now, which obviously have to be removed before merging but this seemed like the easiest way to link questions to code.

My main concern is that having AbstractArrayInterface is somewhat strange to me, probably because I'm missing the point a bit. If it is the abstract supertype for all interface types that should work for AbstractArray, it seems to me like it is a very opinionated way of rewriting code, which seems a bit strange to me.
Additionally, having an abstract type for an interface seems like a bit much to me, as I would expect that the only code that reasonably works for all AbstractArray assumptions is necessarily just the Base implementation.

I like that we are trying to avoid code duplication, but I would honestly expect that if you want to write custom implementations for various functions for your own interface, it is quite likely that you either want a concrete implementation without interfaces, or explicitly dispatch through to the implementation of a different interface. For example, this would work:

@interface MyInterface() function f(args...)
    return @interface OtherInterface() f(args...)
end

I think I would find that a bit easier to follow than the current approach, because now it is virtually impossible to find what code is being called where, since everything is hidden behind macros, and the implementation can be either not "interfaced", abstractly interfaced, or concretely interfaced, based on the given type.

TLDR, maybe we could discuss a bit further and iterate a bit more on the implementation here

[codecov]

Codecov Report

Attention: Patch coverage is 11.11111% with 8 lines in your changes missing coverage. Please review.

Project coverage is 37.17%. Comparing base (d760a1f) to head (3b25ad2).

Files with missing lines	Patch %	Lines
src/interface_function.jl	0.00%	4 Missing ⚠️
src/abstractinterface.jl	0.00%	3 Missing ⚠️
src/traits.jl	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #12      +/-   ##
==========================================
- Coverage   38.41%   37.17%   -1.24%     
==========================================
  Files           9        9              
  Lines         315      312       -3     
==========================================
- Hits          121      116       -5     
- Misses        194      196       +2     

Flag	Coverage Δ
docs	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[mtfishman]

I see your point about AbstractArrayInterface and also about abstract interface types more generally. I think your proposal of removing AbstractArrayInterface and other abstract interface types could make the package conceptually simpler but I don't have a clear picture for how it will work in practice in each case, so I think we'll need to discuss and try it out a bit to see how it goes.

[mtfishman]

I think one of the issues you are identifying in your comments is that AbstractArrayInterface is serving a few purposes right now:

1. A supertype for abstract array interfaces.
2. Defining fallback definitions for array interfaces that don't define interface versions of certain functions that forward to Base versions of functions.
3. Defining fallback definitions for array interfaces that don't define interface versions of certain functions that forward to custom versions of functions (basically, some combination of things that I didn't like how they were implemented in Base, and things I found convenient to define when writing SparseArraysBase.jl that I thought might be generally useful).

In retrospect, 3. is not a good use case for AbstractArrayInterface, and I think your impression is right that it should really just be an implementation of Base functionality. However, if that is the case, probably we can just get rid of @interface ::AbstractArrayInterface ... overloads, and instead enable this generic fallback: https://github.com/ITensor/DerivableInterfaces.jl/blob/main/src/interface_function.jl#L10 which just would just call the Base version of the function if there is no interface overload defined.

Then, for functionality where we want alternative implementations from Base (for example Base.cat, some of the broadcasting functionality, etc.), we could have a strategy of defining interfaces associated with those functions, for example in the case of customizing Base.cat we can just define a new interface GenericCatInterface or something like that, just so we can define @interface ::GenericCatInterface Base.cat(...) (say, as the public API for the code being worked on in #18). Then, types that want to use that version of cat can forward to that interface function.

I'm still ok with having abstract type hierarchies of interfaces, part of that was matching the design of ArrayLayouts.MemoryLayout and Base.Broadcast.BroadcastStyle (for example, I think it is nice to have an AbstractSparseArrayInterface that sparse types can inherit behavior from, but then customize behavior for certain operations, say by defining a DiagonalArrayInterface <: AbstractSparseArrayInterface), but with the plan above we can minimize the uses of it in this package which should lead to simpler code that is easier to understand and reason about.