annotate stable apis

[vince-fugnitto]

Description

As part of Theia v1.0.0, the code should be updated to mark stable apis with the @API annotation. This annotation will help developers recognize stable apis, and if ever updated a version update will be required.

[akosyakov]

I'm not sure about @api annotation. In Theia is everything API. Other projects, like Node.js, defined stability index, i.e api is either unstable, stable or deprecated. I think we can rather use @stable annotation. By default all APIs is unstable meaning it can be broken, if we take care about not breaking some API or going through deprecation policy then it should be annotated as stable.