package nxm.sys.inc;

import java.lang.annotation.Documented;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

/** Marker annotation for Java code that is for <b>PROVISIONAL USE ONLY</b>. This annotation is
 *  used as a marker on code that was recently added and for which the API has not been finalized.
 *  Experienced NeXtMidas users are encouraged to experiment with this code and provide feedback
 *  to the NeXtMidas team; but should do so with the knowledge that the API may be changed or
 *  removed at any time during a beta series. <br>
 *  <br>
 *  Any code marked as provisional in a stable series will remain supported within that stable
 *  series, but may be changed or removed in the subsequent beta series. Code will be marked as
 *  provisional for a maximum of two stable series (except where significant API changes are
 *  made based on user feedback). <br>
 *  <br>
 *  Example:
 *  <pre>
 *    - Method X is added in 3.5.0 and marked as {@link ProvisionalUseOnly}.
 *    - Method X will be "provisional" during the 3.5.x (BETA) and 3.6.x (STABLE) series.
 *    - During the 3.7.x (BETA) or 3.9.x (BETA) series the "provisional" designation will be
 *      removed from Method X (i.e. it becomes fully-supported) unless significant user feedback
 *      indicates a need to revise/remove Method X.
 *  </pre>
 *  @author  J. Czechowski IV
 *  @since   NeXtMidas 3.5.4
 *  @version $Id: ProvisionalUseOnly.java,v 1.2 2015/06/19 17:38:11 ntn Exp $
 */
@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
//@Target is specifically omitted as omitting it permits all targets
public @interface ProvisionalUseOnly {
  /** Description of the provisional designation. The preferred forms for this designation are:
   *  <pre>
   *    "Added in NeXtMidas x.y.z"
   *    "Added in NeXtMidas x.y.z: [details]"
   *  </pre>
   *  @return Description of the provisional designation.
   */
  String value ();
}
