Skip to content

Maturity of documented API members

Status

Accepted.

Context

ADR 0015 decided that plugins only use the public-facing store of the core. As a consequence, getters and actions that were previously considered core-internal and therefore undocumented now have to be part of the exported store, since plugins rely on them.

Documenting them without further qualification would imply that they are stable and part of the public API of POLAR, which they are not.

Decision

Everything that is used across module boundaries is part of the exported store and is documented, but annotated with a maturity tag stating the intended audience:

  • @internal: The member is only used within the core. It is not shown to plugin or client developers.
  • @alpha: The member is used by the core and its plugins, but is not part of the public API. It may change within a major version and is not shown to client developers.
  • @beta: The member is not yet part of the public API, but will probably become part of the public API in a later version.
  • No tag: The member is part of the public API and is subject to SemVer.

The reference documentation is generated for different target audiences (core, plugin and client developers).

Consequences

  • (+) All members used across module boundaries are documented, no matter their maturity.
  • (+) The stability guarantees of a member are explicit and machine-readable.
  • (+) The generated reference can be filtered per target audience.
  • (o) The maturity of a member has to be re-evaluated whenever its usage changes.
  • (-) Members marked @alpha may break for plugin developers within a major version.