package org.checkerframework.checker.i18nformatter.qual;

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.checkerframework.framework.qual.SubtypeOf;

/**
 * This annotation indicates that when a string of the annotated type is passed as the first
 * argument to {@link java.text.MessageFormat#format(String, Object...)}, then the expression that
 * is an argument to the annotation can be passed as the remaining arguments, in varargs style.
 *
 * <p>The annotation is used to annotate a method to ensure that an argument is of a particular type
 * indicated by a format string.
 *
 * <p>Example:
 *
 * <pre> static void method(@I18nFormatFor("#2") String format, Object... arg2) {...}
 *
 * method("{0, number}", 2);</pre>
 *
 * This ensures that the second parameter ("#2") can be passed as the remaining arguments of {@link
 * java.text.MessageFormat#format(String, Object...)}, when the first argument is {@code "format"}.
 *
 * @checker_framework.manual #i18n-formatter-checker Internationalization Format String Checker
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
@SubtypeOf(I18nUnknownFormat.class)
public @interface I18nFormatFor {
    /**
     * Java expression that is an array that can be passed as the second argument to {@link
     * java.text.MessageFormat#format(String, Object...)}, when the annotated String is the first
     * argument.
     *
     * @checker_framework.manual #java-expressions-as-arguments Syntax of Java expressions
     */
    String value();
}
