Parameter Specifications

/**
 * Creates a ParameterSpec from a VariableElement
 * @param element - The variable element from annotation processing
 * @return ParameterSpec initialized from the element
 */
static ParameterSpec get(VariableElement element);

/**
 * Creates a builder for a parameter declaration
 * @param type - The parameter type as TypeName
 * @param name - The parameter name
 * @param modifiers - Optional modifiers for the parameter
 * @return Builder for configuring a parameter
 */
static ParameterSpec.Builder builder(TypeName type, String name, Modifier... modifiers);

/**
 * Creates a builder for a parameter using reflection Type
 * @param type - The parameter type as reflection Type
 * @param name - The parameter name
 * @param modifiers - Optional modifiers for the parameter
 * @return Builder for configuring a parameter
 */
static ParameterSpec.Builder builder(Type type, String name, Modifier... modifiers);

// Simple parameter
ParameterSpec name = ParameterSpec.builder(String.class, "name")
    .build();

// Final parameter
ParameterSpec id = ParameterSpec.builder(int.class, "id", Modifier.FINAL)
    .build();

// Parameterized type parameter
TypeName listOfStrings = ParameterizedTypeName.get(List.class, String.class);
ParameterSpec items = ParameterSpec.builder(listOfStrings, "items")
    .build();

// From annotation processing
ParameterSpec param = ParameterSpec.get(variableElement);

/**
 * Returns the parameter name
 * @return The parameter name
 */
String name();

/**
 * Returns the annotations on this parameter
 * @return List of AnnotationSpec
 */
List<AnnotationSpec> annotations();

/**
 * Returns the modifiers for this parameter
 * @return Set of Modifier (typically empty or contains FINAL)
 */
Set<Modifier> modifiers();

/**
 * Returns the parameter type
 * @return TypeName of the parameter
 */
TypeName type();

/**
 * Returns the Javadoc comment
 * @return CodeBlock containing Javadoc
 */
CodeBlock javadoc();

/**
 * Creates a builder initialized with this parameter's properties
 * @return Builder for modifying this ParameterSpec
 */
ParameterSpec.Builder toBuilder();

/**
 * Adds Javadoc documentation from a format string
 * @param format - Format string for Javadoc
 * @param args - Arguments for format placeholders
 * @return This builder for chaining
 */
ParameterSpec.Builder addJavadoc(String format, Object... args);

/**
 * Adds Javadoc documentation from a CodeBlock
 * @param block - CodeBlock containing Javadoc
 * @return This builder for chaining
 */
ParameterSpec.Builder addJavadoc(CodeBlock block);

ParameterSpec timeout = ParameterSpec.builder(int.class, "timeout")
    .addJavadoc("The timeout in seconds\n")
    .build();

/**
 * Adds multiple annotations
 * @param annotationSpecs - Iterable of annotations to add
 * @return This builder for chaining
 */
ParameterSpec.Builder addAnnotations(Iterable<AnnotationSpec> annotationSpecs);

/**
 * Adds an annotation from an AnnotationSpec
 * @param annotationSpec - The annotation to add
 * @return This builder for chaining
 */
ParameterSpec.Builder addAnnotation(AnnotationSpec annotationSpec);

/**
 * Adds an annotation by ClassName
 * @param annotation - The annotation class name
 * @return This builder for chaining
 */
ParameterSpec.Builder addAnnotation(ClassName annotation);

/**
 * Adds an annotation by Class
 * @param annotation - The annotation class
 * @return This builder for chaining
 */
ParameterSpec.Builder addAnnotation(Class<?> annotation);

// Nullable parameter
ParameterSpec name = ParameterSpec.builder(String.class, "name")
    .addAnnotation(Nullable.class)
    .build();

// NotNull parameter
ParameterSpec email = ParameterSpec.builder(String.class, "email")
    .addAnnotation(NotNull.class)
    .build();

// Custom annotation with members
ParameterSpec value = ParameterSpec.builder(String.class, "value")
    .addAnnotation(AnnotationSpec.builder(Size.class)
        .addMember("min", "$L", 1)
        .addMember("max", "$L", 100)
        .build())
    .build();

// Multiple annotations
ParameterSpec userId = ParameterSpec.builder(String.class, "userId")
    .addAnnotation(NotNull.class)
    .addAnnotation(AnnotationSpec.builder(Pattern.class)
        .addMember("regexp", "$S", "[a-z0-9]+")
        .build())
    .build();

/**
 * Adds modifiers to the parameter
 * @param modifiers - Modifiers to add (typically FINAL)
 * @return This builder for chaining
 */
ParameterSpec.Builder addModifiers(Modifier... modifiers);

/**
 * Adds modifiers from an iterable
 * @param modifiers - Iterable of modifiers to add
 * @return This builder for chaining
 */
ParameterSpec.Builder addModifiers(Iterable<Modifier> modifiers);

ParameterSpec config = ParameterSpec.builder(Configuration.class, "config", Modifier.FINAL)
    .build();

// Or add modifiers later
ParameterSpec data = ParameterSpec.builder(byte[].class, "data")
    .addModifiers(Modifier.FINAL)
    .build();

/**
 * Builds the ParameterSpec with configured properties
 * @return The built ParameterSpec instance
 */
ParameterSpec build();

ParameterSpec description = ParameterSpec.builder(String.class, "description")
    .addAnnotation(Nullable.class)
    .build();

MethodSpec setDescription = MethodSpec.methodBuilder("setDescription")
    .addParameter(description)
    .addStatement("this.description = description")
    .build();

ParameterSpec age = ParameterSpec.builder(int.class, "age")
    .addAnnotation(AnnotationSpec.builder(Min.class)
        .addMember("value", "$L", 0)
        .build())
    .addAnnotation(AnnotationSpec.builder(Max.class)
        .addMember("value", "$L", 150)
        .build())
    .build();

TypeVariableName t = TypeVariableName.get("T");
ParameterSpec item = ParameterSpec.builder(t, "item")
    .build();

MethodSpec add = MethodSpec.methodBuilder("add")
    .addTypeVariable(t)
    .addParameter(item)
    .build();

TypeName listOfStrings = ParameterizedTypeName.get(
    ClassName.get(List.class),
    ClassName.get(String.class)
);
ParameterSpec names = ParameterSpec.builder(listOfStrings, "names")
    .addAnnotation(NotNull.class)
    .build();

ParameterSpec values = ParameterSpec.builder(Object[].class, "values")
    .build();

MethodSpec format = MethodSpec.methodBuilder("format")
    .addParameter(String.class, "pattern")
    .addParameter(values)
    .varargs()
    .build();

TypeName consumer = ParameterizedTypeName.get(
    ClassName.get(Consumer.class),
    ClassName.get(String.class)
);
ParameterSpec callback = ParameterSpec.builder(consumer, "callback")
    .addAnnotation(NotNull.class)
    .build();

MethodSpec process = MethodSpec.methodBuilder("process")
    .addParameter(String.class, "input")
    .addParameter(callback)
    .addStatement("callback.accept(input)")
    .build();

ParameterSpec immutableValue = ParameterSpec.builder(String.class, "value", Modifier.FINAL)
    .addAnnotation(NotNull.class)
    .build();

MethodSpec constructor = MethodSpec.constructorBuilder()
    .addModifiers(Modifier.PUBLIC)
    .addParameter(immutableValue)
    .addStatement("this.value = value")
    .build();

ParameterSpec requestBody = ParameterSpec.builder(User.class, "user")
    .addAnnotation(ClassName.get("org.springframework.web.bind.annotation", "RequestBody"))
    .build();

MethodSpec createUser = MethodSpec.methodBuilder("createUser")
    .addAnnotation(ClassName.get("org.springframework.web.bind.annotation", "PostMapping"))
    .addParameter(requestBody)
    .returns(User.class)
    .build();

class ParameterSpec {
    static ParameterSpec get(VariableElement element);
    static Builder builder(TypeName type, String name, Modifier... modifiers);
    static Builder builder(Type type, String name, Modifier... modifiers);

    String name();
    List<AnnotationSpec> annotations();
    Set<Modifier> modifiers();
    TypeName type();
    CodeBlock javadoc();
    Builder toBuilder();
    boolean equals(Object o);
    int hashCode();
    String toString();
}

class ParameterSpec.Builder {
    ParameterSpec.Builder addJavadoc(String format, Object... args);
    ParameterSpec.Builder addJavadoc(CodeBlock block);
    ParameterSpec.Builder addAnnotations(Iterable<AnnotationSpec> annotationSpecs);
    ParameterSpec.Builder addAnnotation(AnnotationSpec annotationSpec);
    ParameterSpec.Builder addAnnotation(ClassName annotation);
    ParameterSpec.Builder addAnnotation(Class<?> annotation);
    ParameterSpec.Builder addModifiers(Modifier... modifiers);
    ParameterSpec.Builder addModifiers(Iterable<Modifier> modifiers);
    ParameterSpec build();
}