[cosmos-dev] Question about provisional APIs

[David Whiteman <David_Whiteman@xxxxxxxxxx>]

At the last F2F, we discussed the COSMOS
dev process, and in particular how to denote provisional APIs.  It
was decided that we would use Java annotations instead of encoding "provisional"
in the package name.  I'm trying to remember the details of what we
decided.  Did we simply decide to use the approach documented here
in the TPTP API Contract document for stable provisional APIs for all of
our provisional APIs?

http://www.eclipse.org/tptp/home/documents/process/development/api_contract.html

If so, is the following wording sufficient
for putting into our own dev process:

Provisional API is API that can change, but is unlikely
to change in the next release. Such code has the @provisional tag in the
Javadoc. Provisional API is solid but is not public for any number of reasons:
the implementation may fluctuate, the function's quality isn't as high
as we'd like it to be yet, ports to other platforms may be needed, etc.


One question I have is whether we put
the @provisional tag in every method comment, or just the class comment,
or both?  We often have entire interfaces that are considered provisional,
so I didn't know where it should be best indicated.

David