[eclipse-dev] reminders: proper API javaoc and @since 3.0

[Jim des Rivieres <Jim_des_Rivieres@xxxxxxxxxx>]

Some API-related reminders:

Please ensure that all new API elements introduced in 3.0 are properly 
documented with a Javadoc spec and tagged "@since 3.0".  (It's also a good 
idea to do this for non-API elements as well.)

Javadoc should always include @param and @return tags, and @exception tags 
for checked exceptions.  These tags get used by tools (like JDT) for 
tooltips, etc.

When an entire class or interface is tagged @since 3.0, its methods and 
fields should not be tagged. For new API packages, remember to write the 
package.html

Extension points are also considered API elements; the extension point 
schema is equivalent to the Javadoc.

Releasing new code in API packages without accompanying Javadoc specs is a 
very bad idea. Everyone counts on the Javadoc being accurate at all times. 
 If you haven't written the javadoc, you haven't yet designed an API; keep 
this stuff in internal packages until it's presentable.

It takes work to keep the Eclipse APIs in good shape; please do not 
neglect this important task.

---jeem