API Javadoc tags
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:
- reference - whether other components are expected to reference this type by name (default: true); specify "false" to indicate that the type is internal
- implement - whether other components are expected to declare a class that implements this interface (default: true); specify "false" for an interface that other components are not supposed to implement directly; this attribute is ignored for classes, enumerations, and annotation types, none of which can be meaningfully implemented
- subclass - whether other components are expected to declare a class that directly subclasses this class (default: true); specify "false" for a class that other components are not supposed to subclass directly; this attribute is ignored for interfaces, enumerations, and annotation types, none of which can be meaningfully subclassed
- instantiate - whether other components are expected to create instances of this class or annotation type (default: true); specify "false" for a type that other components are not supposed to instantiate directly; this attribute is ignored for interfaces and enumerations, neither of which can be meaningfully instantiated; this attribute is moot for classes that are declared final (or ones with no generally accessible constructors), since the Java compiler and JRE will block outside attempts to instantiate