2024-07-10 –, REPL (2, main stage)
A well defined public API enables users to update a package with confidence that their code will not break and lets IDEs and the REPL help users discover the public functionality of a package. This talk describes currently available mechanisms and community conventions for declaring a public API, highlights the new public keyword and its use in tooling, and discusses future work to help declare APIs more clearly and help folks respect APIs more easily.
Motivation for declaring a public API
- facilitates upgrading packages in conjunction with symver
- documents useful functionality (both to humans and to tooling)
- the existence of a well defined public API prevents folks from using an implicit definition like "is it documented" and therefore allows folks to document internals
The public keyword and it's role in existing conventions
- "if it's in the manual it's public" and why that is problematic for REPL users
- syntax for marking a symbol public
- the current "if it's marked public and documented" convention that Julia itself follows
- what to do about behavior not tied to a specific symbol
- interfaces
What exactly is marked public
- bindings are marked public
- publicity is recursive
- exports are automatically publicised
Tooling support
- REPL helpmode warns displaying the docstring of a nonpublic binding
- REPL autocomplete (#51327)
- other tooling that is added or in progress by the time of the talk
Future work
- marking fields of a struct public
- disabling internal access by default (#52314)
- formally specifying interfaces
I am an artist, scientist, and developer, with a specialty in sorting. Lately I've been exploring how to improve the Julia contributor experience.