[pde-ui-dev] API Javadoc Tag Evolution

[Darin Wright <Darin_Wright@xxxxxxxxxx>]

API Toolers,

Based on feedback we received during milestone 7, API tooling Javadoc tags 
have undergone small changes:

(1) We no longer support the @noextend tag for interfaces. Instead, 
@noimplement indicates that clients may not extend or implement an 
interface.
(2) We no longer support the @noextend tag for methdos. Instead, a new 
@nooverride tag has been added to indicate that clients may not declare a 
method with the same name and signature in a subclass.

PDE user doc will be updated to contain this information. Attached is the 
current specication/user doc for API Javadoc tags:



Darin

Title: API Tooling Javadoc Tags

Defining API Restrictions

API tooling provides Javadoc tags to explicitly document and restrict the use of API. The following tables summarizes the Javadoc tags supported by each member and the semantics of each tag.

A client refers to a plug-in or bundle that requires the bundle where the associated API is defined. Restrictions are not applied in the same bundle where API is defined. For example, a bundle that defines an interface as @noimplement is also allowed to provide an implementation of that interface.

Supported Restriction Tags

	Class	Interface	Method	Constructor	Final Field	Non-Final Field
@noimplement	-		-	-	-	-
@noextend			-	-	-	-
@noinstantiate		-	-	-	-	-
@nooverride	-	-		-	-	-
@noreference	-	-			-

Restriction Semantics

@noimplement	Indicates that clients must not implement this interface. Any class using the implements or extends keyword for the associated interface will be flagged with problem.
@noextend	Indicates that clients must not extend this class. Any class using the extends keyworkd for the associated class will be flagged with a problem.
@noinstantiate	Indicates that clients must not instantiate this class. Any code that instantiates the associated class with any constructor will be flagged with a problem.
@nooverride	Indicates that clients must not declare this method. Any subclass that defines a method with the same name and signature will be flagged with a problem.
@noreference	Indicates that clients must not reference this method, constructor, or non-final field. Any code that directly invokes the associated method or contstructor or references the associated non-final field will be flagged with a problem.