/*
 * Copyright 2015-2017 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.jupiter.api;

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

/**
 * {@code @TestInstance} is a class-level annotation that is used to configure
 * the {@linkplain Lifecycle lifecycle} of test instances for the annotated
 * test class.
 *
 * <p>If {@code @TestInstance} is not declared on a test class, the lifecycle
 * mode will default to {@link Lifecycle#PER_METHOD PER_METHOD}. Note, however,
 * that the lifecycle mode is <em>inherited</em> within test class hierarchies.
 *
 * @author Sam Brannen
 * @since 5.0
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@Documented
public @interface TestInstance {

	/**
	 * Enumeration of test instance lifecycle <em>modes</em>.
	 */
	enum Lifecycle {

		/**
		 * When using this mode, a new test instance will be created once per test class.
		 *
		 * @see #PER_METHOD
		 */
		PER_CLASS,

		/**
		 * When using this mode, a new test instance will be created for each test method
		 * or test factory method.
		 *
		 * <p>This mode is analogous to the behavior found in JUnit versions 1 through 4.
		 *
		 * @see #PER_CLASS
		 */
		PER_METHOD;

	}

	/**
	 * The test instance lifecycle <em>mode</em> to use.
	 */
	Lifecycle value();

}

@@ -848,16 +848,27 @@
 de will 
+implicitly 
 default 
@@ -910,16 +910,19 @@
 METHOD%7D.
+%0A *
  Note, h
@@ -932,20 +932,25 @@
 ver,
-%0A *
  that 
-the
+an explicit
  lif
@@ -989,16 +989,21 @@
 %3E within
+%0A * a
  test cl
@@ -1018,12 +1018,824 @@
 arch
-ies.
+y.%0A *%0A * %3Ch3%3EUse Cases%3C/h3%3E%0A * %3Cp%3ESetting the test instance lifecycle mode to %7B@link Lifecycle.PER_CLASS%0A * PER_CLASS%7D enables the following features.%0A * %3Cul%3E%0A * %3Cli%3EShared test instance state between test methods in a given test class%0A * as well as between non-static %7B@link BeforeAll @BeforeAll%7D and%0A * %7B@link AfterAll @AfterAll%7D methods in the test class.%3C/li%3E%0A * %3Cli%3EDeclaration of %7B@link BeforeAll @BeforeAll%7D and %7B@link AfterAll @AfterAll%7D%0A * methods in %7B@link Nested @Nested%7D test classes.%3C/li%3E%0A * %3Cli%3EDeclaration of %7B@link BeforeAll @BeforeAll%7D and %7B@link AfterAll @AfterAll%7D%0A * on interface %7B@code default%7D methods.%3C/li%3E%0A * %3Cli%3ESimplified declaration of %7B@link BeforeAll @BeforeAll%7D and%0A * %7B@link AfterAll @AfterAll%7D methods in test classes implemented with the Kotlin%0A * programming language.%3C/li%3E%0A * %3C/ul%3E
 %0A *%0A

Document use cases for @TestInstance in JavaDoc