[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
[eclipse-dev] reminders: proper API javaoc and @since 3.0
|
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