/*
 * Copyright 2015-2018 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 v2.0 which
 * accompanies this distribution and is available at
 *
 * http://www.eclipse.org/legal/epl-v20.html
 */

package org.junit.jupiter.api.extension;

import static org.apiguardian.api.API.Status.STABLE;

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;

import org.apiguardian.api.API;

/**
 * {@code @RegisterExtension} is used to register an {@link Extension} via a
 * field in a test class.
 *
 * <p>In contrast to {@link ExtendWith @ExtendWith} which is used to register
 * extensions <em>declaratively</em>, {@code @RegisterExtension} can be used to
 * register an extension <em>programmatically</em> &mdash; for example, in order
 * to pass arguments to the extension's constructor, {@code static} factory
 * method, or builder API.
 *
 * <p>{@code @RegisterExtension} fields must not be {@code private}. If a
 * {@code @RegisterExtension} field is {@code static}, the extension will be
 * registered after extensions registered at the class level via
 * {@code @ExtendWith}; otherwise, the extension will be registered after
 * extensions registered at the method level via {@code @ExtendWith}.
 *
 * <h3>Example Usage</h3>
 *
 * <p>In the following example, the {@code docs} field in the test class is
 * initialized programmatically by supplying a custom {@code lookUpDocsDir()}
 * method to a {@code static} factory method in the {@code DocumentationExtension}.
 * The configured {@code DocumentationExtension} will be automatically registered
 * as an extension. In addition, test methods can access the instance of the
 * extension via the {@code docs} field if necessary.
 *
 * <pre style="code">
 * class DocumentationTests {
 *
 *     static Path lookUpDocsDir() {
 *         // return path to docs dir
 *     }
 *
 *     {@literal @}RegisterExtension
 *     DocumentationExtension docs =
 *         DocumentationExtension.forPath(lookUpDocsDir());
 *
 *     {@literal @}Test
 *     void generateDocumentation() {
 *         // use docs ...
 *     }
 * }</pre>
 *
 * <h3>Supported Extension APIs</h3>
 * <ul>
 * <li>{@link ExecutionCondition}</li>
 * <li>{@link BeforeAllCallback}</li>
 * <li>{@link AfterAllCallback}</li>
 * <li>{@link BeforeEachCallback}</li>
 * <li>{@link AfterEachCallback}</li>
 * <li>{@link BeforeTestExecutionCallback}</li>
 * <li>{@link AfterTestExecutionCallback}</li>
 * <li>{@link TestInstancePostProcessor}</li>
 * <li>{@link ParameterResolver}</li>
 * <li>{@link TestExecutionExceptionHandler}</li>
 * <li>{@link TestTemplateInvocationContextProvider}</li>
 * </ul>
 *
 * @since 5.1
 * @see ExtendWith
 * @see Extension
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@API(status = STABLE, since = "5.1")
public @interface RegisterExtension {
}

@@ -1164,17 +1164,135 @@
 ate%7D
-. If a%0A *
+ or%0A * %7B@code null%7D (when evaluated) but may be either %7B@code static%7D or non-static.%0A *%0A * %3Ch3%3EStatic Fields%3C/h3%3E%0A *%0A * %3Cp%3EIf a
  %7B@c
@@ -1353,24 +1353,27 @@
 xtension
+%0A *
  will be
 %0A * regi
@@ -1364,19 +1364,16 @@
  will be
-%0A *
  registe
@@ -1385,32 +1385,41 @@
 fter extensions 
+that are 
 registered at th
@@ -1435,50 +1435,1133 @@
 evel
+%0A *
  via
-%0A * %7B@code @ExtendWith%7D; otherwise, th
+ %7B@code @ExtendWith%7D. Such %3Cem%3Estatic%3C/em%3E extensions are not limited in%0A * which extension APIs they can implement. Extensions registered via static%0A * fields may therefore implement class-level and instance-level extension APIs%0A * such as %7B@link BeforeAllCallback%7D, %7B@link AfterAllCallback%7D, and%0A * %7B@link TestInstancePostProcessor%7D as well as method-level extension APIs%0A * such as %7B@link BeforeEachCallback%7D, etc.%0A *%0A * %3Ch3%3EInstance Fields%3C/h3%3E%0A *%0A * %3Cp%3EIf a %7B@code @RegisterExtension%7D field is non-static (i.e., an instance%0A * field), the extension will be registered after the test class has been%0A * instantiated and after all %7B@link TestInstancePostProcessor%0A * TestInstancePostProcessors%7D have been given a chance to post-process the%0A * test instance (potentially injecting the instance of the extension to be%0A * used into the annotated field). Thus, if such an %3Cem%3Einstance%3C/em%3E extension%0A * implements class-level or instance-level extension APIs such as%0A * %7B@link BeforeAllCallback%7D, %7B@link AfterAllCallback%7D, or%0A * %7B@link TestInstancePostProcessor%7D those APIs will not be honored. By default,%0A * an instanc
 e ex
@@ -2591,27 +2591,335 @@
 red 
+%3Cem%3E
 after
-%0A * extensions
+%3C/em%3E extensions that are%0A * registered at the method level via %7B@code @ExtendWith%7D; however, if the test%0A * class is configured with%0A * %7B@link org.junit.jupiter.api.TestInstance.Lifecycle @TestInstance(Lifecycle.PER_CLASS)%7D%0A * semantics, an instance extension will be registered %3Cem%3Ebefore%3C/em%3E extensions%0A * that are
  reg

Improve JavaDoc for @RegisterExtension