[Core] Document what Cucumber-JVM considers it public API
[Core] Document what Cucumber-JVM considers it public API

Cucumber-JVMs public API consists of either:

 * Any public class in in the `cucumber.api` package or subpackage
   thereof.
 * Any public class marked with
  `@org.apiguardian.api.API(status = API.Status.STABLE)`.

This dual system will allow us to gradually migrate the package
structure to `io.cucumber`.

While the `api` package makes it clear what is part of the API, it also
forces us to expose more of the API then strictly necessary. It also
creates split packages which will prevent Cucumber from being used
with the Java module system.

See #1536

cucumber/cucumber-jvm,cucumber/cucumber-jvm,cucumber/cucumber-jvm,cucumber/cucumber-jvm,cucumber/cucumber-jvm