The selection process
For the Apertis SDK, this is how we plan to go about defining the APIs:
- Contributor proposes a module for the public API, along with a list of objects and methods that should be exposed
- Collabora goes over the proposed objects and methods making recommendations
- Contributor applies recommendations and establishes API as public and supported
The APIs will be made available in a language to be decided, using a technique to be decided. Most API will also be made available to a webruntime.
Language of choice
Also, GObject Introspection support can also be written for libraries that are not GObject users, such as cairo, which indeed already has introspection support.
Introspection shares some infrastructure with gtk-doc, which is used for building API reference for most GNOME projects. Since gtk-doc understands introspection annotations for a while now, annotations could be added to represent the level of support for a given API, such as unsupported, deprecated, supported, recommended. In fact, annotations do already provide tags such as Since and Deprecated which can be used to indicate from which version a given API item is available or has been deprecated, as well as an Stability tag with values for Stable, Unstable and Private. Those could be used to separate in documentation what should and should not be used.