[TOMAHAWK-1324] New classes should have @since annotations, and classes not intended to be part of the tomahawk "api" should be marked appropriately

• Type: Task
• Status: Closed
• Priority: Blocker
• Resolution: Fixed
• Fix Version/s: 1.1.7
• Assignee: Leonardo Uribe
• Reporter: Simon Kitching
• Created: 03/Sep/08 20:42
• Updated: 04/Sep/08 04:32
• Resolved: 04/Sep/08 04:32

Description

(1)
Adding @since annotations is standard practice. Any class added since 1.1.6 should have an @since 1.1.7 annotation on it. This includes all classes that exist only in the tomahawk 1.2 branch.

(2)
Tomahawk has some classes that are published with the intention that users invoke or subclass them; these are "the public api" of Tomahawk and that means that they should not be modified in binary-incompatible ways in future releases. Such classes need careful review of their apis as it is difficult to fix them later.

Tomahawk also has classes which have the java qualifiers "public" or "protected", but which really are not intended for use by the general public, and which are not guaranteed to have stable apis. At the least we should mark all such classes with a suitable javadoc comment. And ideally such classes should have a name that starts with an underscore.

(3)
Classes that are part of the "stable public api" should not change between releases.

The "clirr" tool can be used to generate a report that compares jars from two releases and creates a report of the differences. This report can then be used to help check 1,2 and 3 above.
Clirr is available as a maven report plugin, or as a standalone commandline tool.