/*
 * Copyright 2015-2016 the original author or authors.
 *
 * All rights reserved. This program and the accompanying materials are
 * made available under the terms of the Eclipse Public License v1.0 which
 * accompanies this distribution and is available at
 *
 * http://www.eclipse.org/legal/epl-v10.html
 */

package org.junit.gen5.commons.meta;

import static org.junit.gen5.commons.meta.API.Usage.Internal;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ ElementType.TYPE, ElementType.METHOD })
// TODO Check if SOURCE is sufficient
@Retention(RetentionPolicy.CLASS)
@Documented
@API(Internal)
public @interface API {

	Usage value();

	enum Usage {

		Deprecated,

		Internal,

		Experimental,

		Maintained,

		Stable

	}

}

@@ -610,16 +610,345 @@
 arget;%0A%0A
+/**%0A * Annotates public types within JUnit 5 to indicate their level of stability%0A * and how they are intended to be used.%0A *%0A * %3Cp%3EIf the annotation is present on a type, it is considered to hold for%0A * all public members of this type as well. A member is allowed to declare a%0A * different %7B@link Usage%7D of lower stability.%0A */%0A
 @Target(
@@ -993,46 +993,8 @@
  %7D)%0A
-// TODO Check if SOURCE is sufficient%0A
 @Ret
@@ -1097,81 +1097,986 @@
 ;%0A%0A%09
-enum Usage %7B%0A%0A%09%09Deprecated,%0A%0A%09%09Internal,%0A%0A%09%09Experimental,%0A%0A%09%09Maintained,%0A
+/**%0A%09 * Indicates the level of stability of an API element.%0A%09 */%0A%09enum Usage %7B%0A%0A%09%09/**%0A%09%09 * Must not be used by any code other than JUnit itself. Might be%0A%09%09 * removed without prior notice.%0A%09%09 */%0A%09%09Internal,%0A%0A%09%09/**%0A%09%09 * Should no longer be used, might disappear in the next minor release.%0A%09%09 */%0A%09%09Deprecated,%0A%0A%09%09/**%0A%09%09 * Intended for new, experimental features where we are looking for feedback.%0A%09%09 *%0A%09%09 * %3Cp%3EUse with caution, might be promoted to %7B@code Maintained%7D or%0A%09%09 * %7B@code Stable%7D in the future, but might also be removed without%0A%09%09 * prior notice.%0A%09%09 */%0A%09%09Experimental,%0A%0A%09%09/**%0A%09%09 * Intended for features that will not be changed in a backwards-%0A%09%09 * incompatible way for at least the next minor release of the current%0A%09%09 * major version. If scheduled for removal, it will be demoted to%0A%09%09 * %7B@code Deprecated%7D first.%0A%09%09 */%0A%09%09Maintained,%0A%0A%09%09/**%0A%09%09 * Intended for features that will not be changed in a backwards-%0A%09%09 * incompatible way in the current major version.%0A%09%09 */
 %0A%09%09S

Document API annotation