Best formalism to define the interface

[gdalle]

When we define the new API, there will be abstract types with some methods that must be implemented. In base Julia, I see two main ways of specifying this (as in, defining the function name, possibly with a generic docstring):

julia> function myfunc1 end
myfunc1 (generic function with 0 methods)

julia> myfunc2(args...) = error("Not implemented")
myfunc2 (generic function with 1 method)

julia> myfunc1(1)
ERROR: MethodError: no method matching myfunc1(::Int64)
Stacktrace:
 [1] top-level scope
   @ REPL[4]:1

julia> myfunc2(1)
ERROR: Not implemented
Stacktrace:
 [1] error(s::String)
   @ Base ./error.jl:35
 [2] myfunc2(args::Int64)
   @ Main ./REPL[2]:1
 [3] top-level scope
   @ REPL[5]:1

I believe a methodless function is better than a single method throwing an error by default. The end result is nearly the same in terms of user experience, but I find the first error clearer because it directly tells you what to implement. @simonschoelly what do you think?

Of course we could also consider more advanced options like Interfaces.jl or InterfaceSpecs.jl but maybe it's a bit overkill?

See also: JuliaGraphs/Graphs.jl#262

[henrik-wolf]

I have been looking at RequiredInterfaces.jl which seems like an option as well. Given that the Graphs interface is quite complex, I am in favour of using some interface package to check for correct implementations. RequiredInterfaces.jl also adds a NotImplementedError which could be used instead of the simple Error: not implemented.

[gdalle]

Yeah since I opened this issue I experimented with RequiredInterfaces and was very satisfied. I would love to see it in action here, plus the customer support I got from the lead dev was top notch.
Once the first PR is merged I'll try to add it

[gdalle]

I'm also curious as to whether traits are actually needed or not. Some are used for dispatch, like is_directed, but some others just forbid operations that could also be prevented with an explicit error.

[gdalle]

Regarding drawbacks of traits:

• Proposals for Graphs.jl 2.0 from the perspective of MultilayerGraphs.jl Graphs.jl#165