org.apiguardian.api

What is it

org.apiguardian.api provides an @API annotation. This gives a structured place to document API stability guarantees.

Why use it

If you are writing an application, generally no API is truly stable. You are free to change whatever you need to in order to make the software work.

Libraries are different. Libraries are used by people whose code you have no control over, but with whom you form an implicit social contract where they trust you to not break their code with new library releases.

Explicitly documenting which elements of an API you are committed to maintaining, which you are experimenting with, and which they really shouldn't be touching is therefore a useful thing to do.

Annotations will show up prominently in generated documentation, which makes them a good mechanism for documenting these guarantees (or lack there-of).

Getting Started

import org.apiguardian.api.API;

public final class MathOps {
    private MathOps() {}

    @API(status = API.Status.STABLE)
    public double pi() {
        return 3.14;
    }

    @API(status = API.Status.EXPERIMENTAL)
    public double tau() {
        return pi() * 2;
    }
}

<- Index