Convention: Coding minimal/required API stubs

General Usage
1

Hi,
Is there a convention around implementing/testing a minimal API for a package?

Take StatsBase.jl/src/statsmodels.jl as the example.
I have read (misread?) that file as indicating: The minimal API functions that a subtype of StatisticalModel should implement, to be a (first-class citizen) StatsBase statistical model.

Is that file an example of the Julia convention for setting out a minimal API?

Related is the call to stop using error(...).

Is there a agreed or emerging convention about how to implement such stubs indicating the functions a developer is left to implement?
Is there an agreed or emerging convention that such minimal API’s should/should-not have tests?

1 Like
2

When there is no fallback method that makes sense, packages usually just define the generic function, eg

function coef end

which introduces it to the namespace and also allows a docstring. This was introduced in Julia 0.4, and code predating this version may just have a method that throws an error.

Julia has no language facilities for formal description of interfaces, but it is prudent to document them somewhere, either in the package docs, the docstring of an absract type, or a function that serves a trait.

3 Likes