Jieko

Documentation as interfaces. 接口(Jiekou) is the Chinese word for Interfaces. This one works with the public keyword.

Julia uses docstrings to define interfaces. This is a flexible way of creating interfaces in a dynamic language, but also creates trouble for automation and tooling. Jieko is a package that provides a infrastructure for defining interfaces that works with DocStringExtension with precisely the signature of the interface.

Installation

Jieko is a   Julia Language   package. To install Jieko, please open Julia's interactive session (known as REPL) and press ] key in the REPL to use the package mode, then type the following command

pkg> add Jieko

Example

You only need to use the @interface macro and if you have DocStringExtensions setup, you can use the INTERFACE stub to generate the interface definition in the docstring similar to the SIGNATURES for methods.

using Jieko: @interface, INTERFACE

"""
$INTERFACE

my lovely interface
"""
@interface jieko(x::Real) = x

we can also compare with the SIGNATURES from DocStringExtensions:

using DocStringExtensions: SIGNATURES

"""
$SIGNATURES

my lovely method
"""
doc_string_ext(x::Real) = x

they result in the following

help?> doc_string_ext
search: doc_string_ext

  doc_string_ext(x)
  

  my lovely method

help?> jieko
search: jieko TestJieko

  public Main.jieko(x::Real)

  my lovely interface

In summary, the @interface macro from Jieko records the precise interface signature of your definition in the docstring, instead of guessing them from Julia's method table (SIGNATURES). DocStringExtensions plugins are provided via INTERFACE and INTERFACE_LIST to generate the interface definition in the docstring.

See the documentation for more details.

License

MIT License