REVISION.md

Criteria for the revision of fastutil's code base

General rules

* All methods overriding some other method must sport
  the @Override annotation.

* All implementation of deprecated methods must
  propagate the deprecation annotation and documentation.

* Annotation must be in the order @Deprecated, @Override,
  @SuppressWarnings.

Type-specific methods

For each new type-specific method, the following must happen:

* The method documentation must contain only a short
  title (more or less copied from the non-specific JDK
  documentation) and a `@see` pointing at the corresponding 
  non-type-specific method.

* The corresponding non-type-specific method must be
  redeclared as @Deprecated with the following documentation
  and annotation.

	 /** {@inheritDoc}
	  * @deprecated Please use the corresponding type-specific method instead. */
	 @Deprecated
	 @Override

* Ideally, one should provide an abstract class which implements
  the non-type-specific methods by delegating the argument
  to the type-specific method, possibly treating separately
  the `null` case. Documentation and annotation should be

	 /** {@inheritDoc}
	  * <p>Delegates to the corresponding type-specific method.
	  * @deprecated Please use the corresponding type-specific method instead. */
	 @Deprecated
	 @Override

* Ideally, the abstract class should implement the type-specific
  methods following the example of the Java Collections Framework.
  For example,

	 /** {@inheritDoc}
	  * <p>This implementation just throws an {@link UnsupportedOperationException}. */
	 @Override

Obsolete type-specific methods

Obsolete methods such as intIterator() should be marked in interfaces as deprecated and documented with a pointer

	/** Returns a type-specific iterator on this elements of this collection.
	 *
	 * @see #iterator()
	 * @deprecated As of <code>fastutil</code> 5, replaced by {@link #iterator()}.
	 */
	@Deprecated

Whenever these methods are implemented, the deprecation must be propagated.

	/**  @{inheritDoc}
	 * @deprecated As of <code>fastutil</code> 5, replaced by {@link #iterator()}. */
	@Deprecated
	@Override

Unnecessary methods

Over the years, a number of duplicate methods have been implemented (e.g., standard versions of type-specific methods). For clarity and simplicity, no unnecessary method should be implemented. In doubt, follow the example of the JDK.