Jump to: navigation, search

API Javadoc tags

The Problem

Certain API usage rules cannot be checked by tools because they are not formally specified in the source code. The most common example is an interface that clients are not intended to implement. It is a breaking API change to add methods to an interface that clients can implement, so it is important to be able to infer this from the API contract. Typically, this is specified in the API contract language, but not in a formal way that tools can detect. There is a PDE API Tools incubator project that is creating tooling for performing API comparisons, checking correctness of API specs, and detecting misbehaving API clients. These tools are weakened by the inability to check for certain API constraints.

The Old Solution

An earlier generation of API tools introduced the notion of a formal component description file to specify these API constraints. The problem with this approach is that the component description files are hard to keep synchronized as the API evolves because they are in a separate document. As a result, component descriptions become stale and the utility of the information is decreased.

The New Solution

The proposed new solution is to encode these API constraints directly into the API javadoc via javadoc tags. Specifically, the following tags are proposed:

  1. @NoReference - Indicates that other bundles must not reference this type by name. I.e., this class is internal. This tag is intended to be used very rarely when an internal class must be exposed for one particular client, but is not intended for general usage.
  2. @NoImplement - Indicates that other bundles must not implement this interface; this attribute is ignored for classes, enumerations, and annotation types, none of which can be meaningfully implemented
  3. @NoSubclass - Indicates that other bundles must not subclass this class; this attribute is ignored for interfaces, enumerations, and annotation types, none of which can be meaningfully subclassed
  4. @NoInstantiate - Indicates that other bundles must not create instances of this class or annotation type; this attribute is ignored for interfaces and enumerations, neither of which can be meaningfully instantiated; this attribute is moot for classes that have no generally accessible constructors, since the Java compiler and JRE will block outside attempts to instantiate

Since tags alone are not sufficient for a human reader, all such tags should be accompanied by a written javadoc contract statement that says the same thing. For example:

  • @NoImplement This interface is not intended to be implemented by clients.
  • @NoSubclass This class is not intended to be subclassed by clients.

The Proposal

The proposal is to encourage Eclipse project component owners to use these tags in their API javadoc. Use of these tags would not be required, but using the tags would allow them to take full advantage of the available API tools. For example, API tools would be able to properly suggest appropriate bundle version number changes, flag contract violations in client code, and detect breaking API contract changes.