Bug 225078

Description Martin Oberhuber 2008-04-01 08:38:02 EDT

As TCF API is becoming more mature, it's very important that we document what classes the client is allowed to extend or instantiate, and what interfaces the client is allowed to implement (or just use).

Eclipse SDK 3.4M6 comes with API Tooling that defines new Javadoc tags for this markup. Content assist is available for these, so you can just @no<Ctrl+Space> to add the tag:
  @noextend, @noimplement, @noinstantiate, @noreference
See 
  http://wiki.eclipse.org/API_Javadoc_tags
  http://wiki.eclipse.org/API_Tooling_User_Guide
  http://wiki.eclipse.org/Api_Tooling

As example, in order to assure binary compatibility with future incarnations of TCF, any class or interface that just declares constants must be marked @noextend because otherwise addition of constants could lead to binary API breakage when a client subclasses that class and adds a method with the same name as an added field in the base class.
  http://wiki.eclipse.org/Evolving_Java-based_APIs

Therefore, e.g. 
  ErrorCodes should be an interface with @noimplement
  Base64 should be @noextend @noinstantiate
  IChannel should be @noimplement with a hint that clients should extend 
     AbstractChannel instead
  ...