/*
 * 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.params;

import static org.junit.platform.commons.meta.API.Usage.Experimental;

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.junit.jupiter.api.TestTemplate;
import org.junit.jupiter.api.extension.ExtendWith;
import org.junit.platform.commons.meta.API;

/**
 * {@code @ParameterizedTest} is used to signal that the annotated method is a
 * <em>parameterized test</em> method.
 *
 * <p>{@code @ParameterizedTest} methods must specify at least one
 * {@link org.junit.jupiter.params.provider.ArgumentsProvider} via the
 * {@link org.junit.jupiter.params.provider.ArgumentsSource @ArgumentsSource}
 * or a corresponding composed annotation. The provider is responsible for
 * providing a {@link java.util.stream.Stream} of
 * {@link org.junit.jupiter.params.provider.Arguments} that will be used to
 * invoke the {@code @ParameterizedTest} method. The method may have additional
 * parameters to be resolved by other
 * {@link org.junit.jupiter.api.extension.ParameterResolver ParameterResolvers}
 * at the end of the method's parameter list.
 *
 * <p>Method parameters may use
 * {@link org.junit.jupiter.params.converter.ConvertWith @ConvertWith}
 * or a corresponding composed annotation to specify an explicit
 * {@link org.junit.jupiter.params.converter.ArgumentConverter}.
 *
 * <p>{@code @ParameterizedTest} may also be used as a meta-annotation in order to
 * create a custom <em>composed annotation</em> that inherits the semantics
 * of {@code @ParameterizedTest}.
 *
 * <p>{@code @ParameterizedTest} methods must not be {@code private} or {@code static}.
 *
 * @since 5.0
 * @see org.junit.jupiter.params.provider.ArgumentsSource
 * @see org.junit.jupiter.params.provider.CsvFileSource
 * @see org.junit.jupiter.params.provider.CsvSource
 * @see org.junit.jupiter.params.provider.EnumSource
 * @see org.junit.jupiter.params.provider.MethodSource
 * @see org.junit.jupiter.params.provider.ValueSource
 * @see org.junit.jupiter.params.converter.ConvertWith
 */
@Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
@API(Experimental)
@TestTemplate
@ExtendWith(ParameterizedTestExtension.class)
public @interface ParameterizedTest {

	/**
	 * @return a custom display name; never blank or consisting solely of
	 * whitespace
	 */
	// TODO [#830] Document name().
	String name() default "[{index}] {arguments}";

}

@@ -2707,38 +2707,82 @@
 %09 * 
-@return a custom display name;
+The name pattern to be used for invocations of the parameterized test;%0A%09 *
  nev
@@ -2813,20 +2813,16 @@
 olely of
-%0A%09 *
  whitesp
@@ -2828,46 +2828,456 @@
 pace
+.
 %0A%09 *
-/%0A%09// TODO %5B#830%5D Document name().
+%0A%09 * %3Cp%3EYou may use the following placeholders:%0A%09 * %3Cul%3E%0A%09 * %3Cli%3E%7B@code %7Bindex%7D%7D: the current invocation index (1-based)%3C/li%3E%0A%09 * %3Cli%3E%7B@code %7Barguments%7D%7D: the complete, comma-separated arguments list%3C/li%3E%0A%09 * %3Cli%3E%7B@code %7B0%7D%7D, %7B@code %7B1%7D%7D, etc.: an individual argument%3C/li%3E%0A%09 * %3C/ul%3E%0A%09 *%0A%09 * %3Cp%3EFor the latter, you may use %7B@link java.text.MessageFormat%7D patterns%0A%09 * to customize formatting of values.%0A%09 *%0A%09 * @see java.text.MessageFormat%0A%09 */
 %0A%09St

Document org.junit.jupiter.params.ParameterizedTest#name