### Create ClassName instances

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/types.md

Examples of creating ClassName instances from classes, packages, and nested structures.

```java
ClassName string = ClassName.get(String.class);
ClassName list = ClassName.get("java.util", "List");
ClassName mapEntry = ClassName.get("java.util", "Map", "Entry");
```

--------------------------------

### Common CodeBlock Usage Patterns

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/CodeBlock.md

Examples demonstrating simple code generation, statement building with types, control flow structures, and try-catch blocks.

```java
import com.squareup.javapoet.*;

// Simple code block
CodeBlock simple = CodeBlock.of("int x = $L", 42);

// Statement with types
CodeBlock withTypes = CodeBlock.builder()
    .addStatement("$T list = new $T<>()", List.class, ArrayList.class)
    .addStatement("list.add($S)", "item")
    .build();

// Control flow
CodeBlock withFlow = CodeBlock.builder()
    .beginControlFlow("for (int i = 0; i < $L; i++)", 10)
    .addStatement("$T.out.println(i)", System.class)
    .endControlFlow()
    .build();

// Complex example: try-catch
CodeBlock tryCatch = CodeBlock.builder()
    .beginControlFlow("try")
    .addStatement("$T.sleep(1000)", Thread.class)
    .nextControlFlow("catch ($T e)", InterruptedException.class)
    .addStatement("$T.out.println($S)", System.class, "Interrupted")
    .endControlFlow()
    .build();
```

--------------------------------

### WildcardTypeName Usage Examples

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/types.md

Examples for creating subtype and supertype wildcards and using them within parameterized types and method parameters.

```java
// ? extends Number
WildcardTypeName extendsNumber = WildcardTypeName.subtypeOf(Number.class);

// ? super String
WildcardTypeName superString = WildcardTypeName.supertypeOf(String.class);

// In parameterized type: List<? extends Number>
ParameterizedTypeName bounded = ParameterizedTypeName.get(
    ClassName.get(List.class),
    WildcardTypeName.subtypeOf(Number.class)
);

// Method parameter: void process(List<? super Number> items)
MethodSpec process = MethodSpec.methodBuilder("process")
    .addParameter(
        ParameterizedTypeName.get(
            ClassName.get(List.class),
            WildcardTypeName.supertypeOf(Number.class)
        ),
        "items"
    )
    .returns(void.class)
    .build();
```

--------------------------------

### Build FieldSpec Instances

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/FieldSpec.md

Examples of creating FieldSpec instances using the builder pattern with initializers and modifiers.

```java
FieldSpec count = FieldSpec.builder(int.class, "count", Modifier.PRIVATE)
    .initializer("0")
    .build();

FieldSpec name = FieldSpec.builder(String.class, "name")
    .addModifiers(Modifier.PRIVATE, Modifier.FINAL)
    .build();
```

--------------------------------

### Basic Type Usage

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/types.md

Examples of assigning primitive and class-based types to variables.

```java
TypeName intType = TypeName.INT;
TypeName stringType = ClassName.get(String.class);
TypeName voidReturn = TypeName.VOID;
```

--------------------------------

### TypeVariableName Usage Examples

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/types.md

Examples for creating unbounded, bounded, and multi-bounded type variables, and using them in MethodSpec.

```java
// Unbounded: <T>
TypeVariableName t = TypeVariableName.get("T");

// Bounded: <T extends Number>
TypeVariableName bounded = TypeVariableName.get("T", Number.class);

// Multiple bounds: <T extends Comparable & Serializable>
TypeVariableName multi = TypeVariableName.get("T",
    ClassName.get(Comparable.class),
    ClassName.get(Serializable.class)
);

// In method signature
MethodSpec max = MethodSpec.methodBuilder("max")
    .addTypeVariable(bounded)
    .addParameter(bounded, "a")
    .addParameter(bounded, "b")
    .returns(bounded)
    .addStatement("return $N.compareTo($N) > 0 ? $N : $N", "a", "b", "a", "b")
    .build();
```

--------------------------------

### CodeBlock Placeholders

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/CodeBlock.md

A reference guide for the placeholders used within CodeBlock to inject literals, strings, types, names, and control formatting.

```APIDOC
## CodeBlock Placeholders

### $L - Literal
Emits a value with no escaping or modification. Valid types: String, number, boolean, TypeSpec, AnnotationSpec, CodeBlock.

### $S - String Literal
Emits a string with quotes and proper escaping. Valid types: String.

### $T - Type Reference
Emits a type reference and automatically imports the type. Valid types: Class, Type, TypeMirror, TypeName.

### $N - Name
Emits a name with collision avoidance. Valid types: String, CharSequence, ParameterSpec, FieldSpec, MethodSpec, TypeSpec.

### $$ - Escaped Dollar Sign
Emits a literal dollar sign.

### $W - Smart Wrapping
Emits a space that can be replaced with a newline for line wrapping.

### $Z - Zero-Width Wrapping
Emits nothing if not wrapping (zero-width space).

### $> and $< - Indentation
Increases or decreases the indentation level.

### $[ and $] - Statement Markers
Marks the beginning and end of a statement for indentation purposes.
```

--------------------------------

### ArrayTypeName Usage

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/types.md

Examples of creating single and multi-dimensional array types.

```java
ArrayTypeName stringArray = ArrayTypeName.of(String.class);
// String[]

ArrayTypeName twoDim = ArrayTypeName.of(ArrayTypeName.of(int.class));
// int[][]
```

--------------------------------

### Handle ClassName validation errors

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/errors.md

Examples of invalid package and class name formats that trigger exceptions.

```java
// Error: Invalid package name format
ClassName.get("java..util", "List");  // Double dots invalid

// Error: Invalid class name
ClassName.get("java.util", "");  // Empty class name
```

--------------------------------

### Generate a Simple Class with JavaPoet

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/README.md

Constructs a HelloWorld class with a main method and writes it to the specified directory.

```java
import com.squareup.javapoet.*;
import javax.lang.model.element.Modifier;

// Create a method
MethodSpec main = MethodSpec.methodBuilder("main")
    .addModifiers(Modifier.PUBLIC, Modifier.STATIC)
    .returns(void.class)
    .addParameter(String[].class, "args")
    .addStatement("$T.out.println($S)", System.class, "Hello, JavaPoet!")
    .build();

// Create a class
TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
    .addModifiers(Modifier.PUBLIC, Modifier.FINAL)
    .addMethod(main)
    .build();

// Create a file
JavaFile javaFile = JavaFile.builder("com.example", helloWorld)
    .build();

// Write to file system
javaFile.writeTo(Paths.get("src/main/java"));
```

```java
package com.example;

public final class HelloWorld {
  public static void main(String[] args) {
    System.out.println("Hello, JavaPoet!");
  }
}
```

--------------------------------

### Construct methods with parameters

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/ParameterSpec.md

Demonstrates creating parameters and adding them to a MethodSpec, either as pre-built objects or directly within the method builder.

```java
import com.squareup.javapoet.*;
import javax.lang.model.element.Modifier;

// Create parameters for a method
ParameterSpec firstName = ParameterSpec.builder(String.class, "firstName")
    .addJavadoc("the person's first name\n")
    .build();

ParameterSpec lastName = ParameterSpec.builder(String.class, "lastName")
    .addJavadoc("the person's last name\n")
    .build();

ParameterSpec age = ParameterSpec.builder(int.class, "age")
    .addJavadoc("the person's age\n")
    .build();

// Create a method using these parameters
MethodSpec constructor = MethodSpec.constructorBuilder()
    .addModifiers(Modifier.PUBLIC)
    .addParameter(firstName)
    .addParameter(lastName)
    .addParameter(age)
    .addStatement("this.firstName = $N", "firstName")
    .addStatement("this.lastName = $N", "lastName")
    .addStatement("this.age = $N", "age")
    .build();

// Alternative: add parameters directly
MethodSpec method = MethodSpec.methodBuilder("process")
    .addModifiers(Modifier.PUBLIC)
    .addParameter(String.class, "input")
    .addParameter(int.class, "count")
    .addParameter(boolean.class, "debug")
    .returns(String.class)
    .addStatement("return $S", "processed")
    .build();
```

--------------------------------

### Handling File System IOExceptions

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/errors.md

Shows how to catch IOExceptions when writing generated files to the file system.

```java
Path directory = Paths.get("/nonexistent/path");

try {
    javaFile.writeTo(directory);
} catch (IOException e) {
    System.out.println("Failed to write file: " + e.getMessage());
    e.printStackTrace();
}
```

--------------------------------

### ParameterizedTypeName Usage

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/types.md

Examples of creating generic types, including nested generics and wildcards.

```java
// List<String>
ParameterizedTypeName listOfStrings = ParameterizedTypeName.get(
    ClassName.get(List.class),
    ClassName.get(String.class)
);

// Map<String, Integer>
ParameterizedTypeName stringIntMap = ParameterizedTypeName.get(
    ClassName.get("java.util", "Map"),
    ClassName.get(String.class),
    ClassName.get(Integer.class)
);

// Nested generics: List<? extends Number>
ParameterizedTypeName bounded = ParameterizedTypeName.get(
    ClassName.get(List.class),
    WildcardTypeName.subtypeOf(Number.class)
);
```

--------------------------------

### Initialize TypeName constants and classes

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/TypeName.md

Use predefined constants for primitives or ClassName.get for standard classes.

```java
TypeName intType = TypeName.INT;
TypeName stringType = ClassName.get(String.class);
```

--------------------------------

### Add Members to AnnotationSpec

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/AnnotationSpec.md

Example of chaining addMember calls to define annotation values.

```java
builder.addMember("value", "$S", "test value")
       .addMember("count", "$L", 42)
       .addMember("enabled", "$L", true);
```

--------------------------------

### build()

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/JavaFile.md

Finalizes the configuration and creates the immutable JavaFile instance.

```APIDOC
## Builder.build()

### Description
Creates the immutable JavaFile instance based on the current builder configuration.

### Returns
- **JavaFile** - The configured JavaFile instance.
```

--------------------------------

### Project File Structure

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/INDEX.md

Displays the directory layout of the documentation project.

```text
output/
├── README.md                          # Main entry point
├── INDEX.md                           # This file
├── types.md                           # Type system reference
├── configuration.md                   # Configuration guide
├── errors.md                          # Error reference
└── api-reference/
    ├── JavaFile.md
    ├── TypeSpec.md
    ├── MethodSpec.md
    ├── CodeBlock.md
    ├── FieldSpec.md
    ├── ParameterSpec.md
    ├── AnnotationSpec.md
    ├── TypeName.md
    ├── ClassName.md
    └── ArrayTypeName.md
```

--------------------------------

### Configure Sonatype credentials

Source: https://github.com/fabricmc/javapoet/blob/master/RELEASING.md

Add your Sonatype Nexus credentials to the ~/.m2/settings.xml file to enable artifact deployment.

```xml
<settings>
  <servers>
    <server>
      <id>sonatype-nexus-staging</id>
      <username>your-nexus-username</username>
      <password>your-nexus-password</password>
    </server>
  </servers>
</settings>
```

--------------------------------

### Handle ClassName null argument errors

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/errors.md

Examples of passing null arguments to ClassName methods, resulting in NullPointerException.

```java
// NullPointerException
ClassName.get(null);
ClassName.get("java.util", null);
```

--------------------------------

### Create a simple type reference

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/ClassName.md

Use ClassName to define types and build methods with parameterized return types.

```java
import com.squareup.javapoet.*;
import javax.lang.model.element.Modifier;

// Create a method returning List<String>
ClassName list = ClassName.get("java.util", "List");
ClassName string = ClassName.get(String.class);

ParameterizedTypeName listOfStrings = ParameterizedTypeName.get(list, string);

MethodSpec getItems = MethodSpec.methodBuilder("getItems")
    .returns(listOfStrings)
    .addModifiers(Modifier.PUBLIC)
    .addStatement("return new $T<>()", ClassName.get("java.util", "ArrayList"))
    .build();
```

--------------------------------

### Generating HelloWorld with JavaPoet

Source: https://github.com/fabricmc/javapoet/blob/master/README.md

Uses MethodSpec and TypeSpec to programmatically construct the HelloWorld class and write it to standard output.

```java
MethodSpec main = MethodSpec.methodBuilder("main")
    .addModifiers(Modifier.PUBLIC, Modifier.STATIC)
    .returns(void.class)
    .addParameter(String[].class, "args")
    .addStatement("$T.out.println($S)", System.class, "Hello, JavaPoet!")
    .build();

TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
    .addModifiers(Modifier.PUBLIC, Modifier.FINAL)
    .addMethod(main)
    .build();

JavaFile javaFile = JavaFile.builder("com.example.helloworld", helloWorld)
    .build();

javaFile.writeTo(System.out);
```

--------------------------------

### Create a JavaFile Builder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/JavaFile.md

Initializes a new JavaFile builder with a package name and a TypeSpec.

```java
JavaFile file = JavaFile.builder("com.example", typeSpec)
    .build();
```

--------------------------------

### Configure MethodSpec with Builder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/configuration.md

Demonstrates building a public static method with generic type variables, parameters, exceptions, and a return type.

```java
MethodSpec method = MethodSpec.methodBuilder("process")
    .addJavadoc("Process the input.\n")
    .addModifiers(Modifier.PUBLIC, Modifier.STATIC)
    .addTypeVariable(TypeVariableName.get("T"))
    .addParameter(String.class, "input")
    .addException(IOException.class)
    .returns(String.class)
    .addStatement("return $N.trim()", "input")
    .build();
```

--------------------------------

### Builder.add(String, Map)

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/CodeBlock.md

Adds code with named placeholders.

```APIDOC
## Builder add(String format, Map<String, ?> args)

### Description
Adds code with named placeholders. Use syntax $argumentName:X where X is the placeholder type.

### Parameters
- **format** (String) - Required - Format string with named placeholders
- **args** (Map<String, ?>) - Required - Map of argument names to values

### Returns
- **Builder** - Builder for chaining.
```

--------------------------------

### Define methods and constructors with MethodSpec

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/MethodSpec.md

Demonstrates creating standard methods, control flow blocks, generic methods, and constructors using the MethodSpec builder.

```java
import com.squareup.javapoet.*;
import javax.lang.model.element.Modifier;

// Simple method
MethodSpec compareTo = MethodSpec.methodBuilder("compareTo")
    .addModifiers(Modifier.PUBLIC)
    .returns(int.class)
    .addParameter(String.class, "other")
    .addStatement("return this.$N.compareTo($N)", "value", "other")
    .build();

// Method with control flow
MethodSpec validate = MethodSpec.methodBuilder("validate")
    .addModifiers(Modifier.PUBLIC)
    .returns(void.class)
    .beginControlFlow("if ($N == null)", "value")
    .addStatement("throw new $T($S)", IllegalArgumentException.class, "value is null")
    .endControlFlow()
    .build();

// Method with generics
TypeVariableName t = TypeVariableName.get("T", Comparable.class);
MethodSpec max = MethodSpec.methodBuilder("max")
    .addModifiers(Modifier.PUBLIC, Modifier.STATIC)
    .addTypeVariable(t)
    .returns(t)
    .addParameter(t, "a")
    .addParameter(t, "b")
    .addStatement("return $N.compareTo($N) > 0 ? $N : $N", "a", "b", "a", "b")
    .build();

// Constructor
MethodSpec constructor = MethodSpec.constructorBuilder()
    .addModifiers(Modifier.PUBLIC)
    .addParameter(String.class, "name")
    .addParameter(int.class, "age")
    .addStatement("this.$N = $N", "name", "name")
    .addStatement("this.$N = $N", "age", "age")
    .build();
```

--------------------------------

### Generate and write a Java class file

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/JavaFile.md

Constructs a class with a main method and writes it to the specified file system path. Requires imports from com.squareup.javapoet and standard Java libraries.

```java
import com.squareup.javapoet.*;
import javax.lang.model.element.Modifier;
import java.nio.file.Paths;

// Create a method
MethodSpec main = MethodSpec.methodBuilder("main")
    .addModifiers(Modifier.PUBLIC, Modifier.STATIC)
    .returns(void.class)
    .addParameter(String[].class, "args")
    .addStatement("$T.out.println($S)", System.class, "Hello, World!")
    .build();

// Create a class
TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
    .addModifiers(Modifier.PUBLIC, Modifier.FINAL)
    .addMethod(main)
    .build();

// Create and write file
JavaFile javaFile = JavaFile.builder("com.example", helloWorld)
    .addFileComment("Generated code. Do not edit.\n")
    .build();

// Write to file system
javaFile.writeTo(Paths.get("src/main/java"));
```

--------------------------------

### Add Static and Instance Initializers

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/README.md

Adds static and instance initialization blocks to a class using CodeBlock.

```java
TypeSpec initialized = TypeSpec.classBuilder("Initialized")
    .addField(int.class, "count", Modifier.PRIVATE)
    .addStaticBlock(CodeBlock.of("System.out.println($S);", "Initializing..."))
    .addInitializerBlock(CodeBlock.of("count = 0;"))
    .build();
```

--------------------------------

### Create Simple Annotations

Source: https://github.com/fabricmc/javapoet/blob/master/README.md

Apply standard annotations to methods using addAnnotation.

```java
MethodSpec toString = MethodSpec.methodBuilder("toString")
    .addAnnotation(Override.class)
    .returns(String.class)
    .addModifiers(Modifier.PUBLIC)
    .addStatement("return $S", "Hoverboard")
    .build();
```

```java
  @Override
  public String toString() {
    return "Hoverboard";
  }
```

--------------------------------

### CodeBlock.of(String format, Object... args)

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/CodeBlock.md

Creates a simple CodeBlock from a format string and variable arguments.

```APIDOC
## CodeBlock.of(String format, Object... args)

### Description
Creates a new CodeBlock instance using a format string with placeholders and a variable number of arguments.

### Parameters
- **format** (String) - Required - The code template string containing placeholders like $L, $S, $T, or $N.
- **args** (Object...) - Required - The values to substitute into the placeholders.

### Example
```java
CodeBlock simple = CodeBlock.of("int x = $L", 42);
```
```

--------------------------------

### Reference Non-Existent Classes

Source: https://github.com/fabricmc/javapoet/blob/master/README.md

Demonstrates referencing classes that do not exist yet using ClassName, which still results in correct import generation.

```java
ClassName hoverboard = ClassName.get("com.mattel", "Hoverboard");

MethodSpec today = MethodSpec.methodBuilder("tomorrow")
    .returns(hoverboard)
    .addStatement("return new $T()", hoverboard)
    .build();
```

```java
package com.example.helloworld;

import com.mattel.Hoverboard;

public final class HelloWorld {
  Hoverboard tomorrow() {
    return new Hoverboard();
  }
}
```

--------------------------------

### Configure JavaFile with Builder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/configuration.md

Use JavaFile.Builder to define package, imports, indentation, and file-level comments.

```java
JavaFile javaFile = JavaFile.builder("com.example", typeSpec)
    .addFileComment("Copyright (C) 2024\n")
    .addStaticImport(Collections.class, "emptyList", "sort")
    .skipJavaLangImports(true)
    .indent("\t")
    .build();
```

--------------------------------

### Build JavaFile

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/JavaFile.md

Finalizes the configuration and creates an immutable JavaFile instance.

```java
JavaFile build()
```

--------------------------------

### Handle exceptions with try/catch

Source: https://github.com/fabricmc/javapoet/blob/master/README.md

Demonstrates using nextControlFlow for try/catch blocks.

```java
MethodSpec main = MethodSpec.methodBuilder("main")
    .beginControlFlow("try")
    .addStatement("throw new Exception($S)", "Failed")
    .nextControlFlow("catch ($T e)", Exception.class)
    .addStatement("throw new $T(e)", RuntimeException.class)
    .endControlFlow()
    .build();
```

```java
void main() {
  try {
    throw new Exception("Failed");
  } catch (Exception e) {
    throw new RuntimeException(e);
  }
}
```

--------------------------------

### Create a simple parameter

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/ParameterSpec.md

Defines a basic parameter with a specified type and name.

```java
ParameterSpec name = ParameterSpec.builder(String.class, "name")
    .build();
```

--------------------------------

### Create a method using methodBuilder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/MethodSpec.md

Initializes a new method definition with parameters and a code body.

```java
MethodSpec sayHello = MethodSpec.methodBuilder("sayHello")
    .addParameter(String.class, "name")
    .returns(void.class)
    .addStatement("$T.out.println($S + $N)", System.class, "Hello, ", "name")
    .build();
```

--------------------------------

### Define a method body with raw strings

Source: https://github.com/fabricmc/javapoet/blob/master/README.md

Demonstrates defining a method body using a raw string block.

```java
MethodSpec main = MethodSpec.methodBuilder("main")
    .addCode(""
        + "int total = 0;\n"
        + "for (int i = 0; i < 10; i++) {\n"
        + "  total += i;\n"
        + "}\n")
    .build();
```

```java
void main() {
  int total = 0;
  for (int i = 0; i < 10; i++) {
    total += i;
  }
}
```

--------------------------------

### Using Named Placeholders in CodeBlock

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/configuration.md

Demonstrates the use of named placeholders with a map of arguments to define loop bounds.

```java
// Format: $argumentName:typeChar
Map<String, Object> args = new LinkedHashMap<>();
args.put("count", 10);
CodeBlock.of("for (int i = 0; i < $count:L; i++)", args);
```

--------------------------------

### Type Annotations

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/types.md

Demonstrates how to apply annotations to TypeName instances using the annotated method.

```APIDOC
## Type Annotations

### Description
Apply Java 8+ type annotations to TypeName subclasses.

### Methods
- **annotated(List<AnnotationSpec> annotations)**: Returns a new TypeName with the specified annotations.
- **isAnnotated()**: Returns true if the type has annotations.
- **withoutAnnotations()**: Returns the underlying type without annotations.
- **getAnnotations()**: Returns the list of annotations on the type.
```

--------------------------------

### Create an interface builder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/TypeSpec.md

Initializes a builder for a new interface type.

```java
TypeSpec myInterface = TypeSpec.interfaceBuilder("MyInterface")
    .build();
```

--------------------------------

### Create ClassName Instances

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/TypeName.md

Construct ClassName objects for fully-qualified class names.

```java
ClassName list = ClassName.get("java.util", "List");
ClassName mapEntry = ClassName.get("java.util", "Map", "Entry");
```

--------------------------------

### Builder.add(String, Object...)

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/CodeBlock.md

Adds code with format placeholders using relative arguments.

```APIDOC
## Builder add(String format, Object... args)

### Description
Adds code with format placeholders. Each placeholder in the format string corresponds to the next argument in order.

### Parameters
- **format** (String) - Required - Format string with $L, $T, $S, etc. placeholders
- **args** (Object...) - Optional - Values to substitute

### Returns
- **Builder** - Builder for chaining.
```

--------------------------------

### Generate an Array Utility Class with JavaPoet

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/ArrayTypeName.md

Demonstrates creating a utility class with methods that accept and return primitive and generic array types.

```java
import com.squareup.javapoet.*;
import javax.lang.model.element.Modifier;

// Method: int[] reverse(int[] array)
MethodSpec reverse = MethodSpec.methodBuilder("reverse")
    .addModifiers(Modifier.PUBLIC, Modifier.STATIC)
    .addParameter(ArrayTypeName.of(int.class), "array")
    .returns(ArrayTypeName.of(int.class))
    .addStatement("$T result = new int[$N.length]", int[].class, "array")
    .beginControlFlow("for (int i = 0; i < $N.length; i++)", "array")
    .addStatement("result[i] = $N[$N.length - 1 - i]", "array", "array")
    .endControlFlow()
    .addStatement("return result")
    .build();

// Method: <T> T[] copy(T[] array)
TypeVariableName t = TypeVariableName.get("T");
MethodSpec copy = MethodSpec.methodBuilder("copy")
    .addModifiers(Modifier.PUBLIC, Modifier.STATIC)
    .addTypeVariable(t)
    .addParameter(ArrayTypeName.of(t), "array")
    .returns(ArrayTypeName.of(t))
    .addStatement("return $T.copyOf($N, $N.length)", Arrays.class, "array", "array")
    .build();

TypeSpec arrayUtils = TypeSpec.classBuilder("ArrayUtils")
    .addModifiers(Modifier.PUBLIC, Modifier.FINAL)
    .addMethod(reverse)
    .addMethod(copy)
    .build();

JavaFile javaFile = JavaFile.builder("com.example.util", arrayUtils)
    .build();
```

--------------------------------

### Smart wrapping with $W

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/CodeBlock.md

Emits a space that can be replaced with a newline for line wrapping, preferring to wrap before 100 columns.

```java
CodeBlock.of("long $W declaration $W = $L", "variableName", value);
```

--------------------------------

### ClassName.get(String, String, String...)

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/ClassName.md

Creates a ClassName instance for a specific package and class name, including support for nested classes.

```APIDOC
## ClassName.get(String packageName, String simpleName, String... simpleNames)

### Description
Creates a ClassName instance representing a fully qualified class name. Additional arguments can be provided to represent nested classes.

### Signature
public static ClassName get(String packageName, String simpleName, String... simpleNames)

### Example
// Reference Map.Entry
ClassName mapEntry = ClassName.get("java.util", "Map", "Entry");
```

--------------------------------

### Write JavaFile to File

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/JavaFile.md

Legacy method to write the source file to a directory using java.io.File.

```java
javaFile.writeTo(new File("src/main/java"));
```

--------------------------------

### CodeBlock.toBuilder()

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/CodeBlock.md

Returns a new builder initialized with this code block's content.

```APIDOC
## Builder toBuilder()

### Description
Returns a new builder initialized with this code block's content.

### Returns
- **Builder** - Builder with current code block copied.
```

--------------------------------

### Configure CodeBlock with Builder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/configuration.md

Use CodeBlock.builder to construct code segments using format strings and placeholder arguments.

```java
CodeBlock block = CodeBlock.builder()
    .addStatement("$T list = new $T<>()", List.class, ArrayList.class)
    .addStatement("list.add($S)", "item")
    .beginControlFlow("for ($T item : $N)", String.class, "list")
    .addStatement("$T.out.println($N)", System.class, "item")
    .endControlFlow()
    .build();
```

--------------------------------

### Builder.build()

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/CodeBlock.md

Creates the immutable CodeBlock instance.

```APIDOC
## CodeBlock build()

### Description
Creates the immutable CodeBlock instance.

### Returns
- **CodeBlock** - Configured CodeBlock.
```

--------------------------------

### Create a class builder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/TypeSpec.md

Initializes a builder for a new class type.

```java
TypeSpec myClass = TypeSpec.classBuilder("MyClass")
    .build();
```

--------------------------------

### Using Correct TypeName Factories

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/errors.md

Recommends using TypeName factory methods instead of manual instantiation.

```java
// Good: Use TypeName factory methods
TypeName type = TypeName.get(String.class);

// Avoid: Creating types without proper factory
// TypeName type = new ClassName(...);  // Wrong!
```

--------------------------------

### Code Block Argument Formatting

Source: https://github.com/fabricmc/javapoet/blob/master/README.md

Demonstrates different ways to pass arguments into code blocks using relative, positional, or named placeholders.

```java
CodeBlock.builder().add("I ate $L $L", 3, "tacos")
```

```java
CodeBlock.builder().add("I ate $2L $1L", "tacos", 3)
```

```java
Map<String, Object> map = new LinkedHashMap<>();
map.put("food", "tacos");
map.put("count", 3);
CodeBlock.builder().addNamed("I ate $count:L $food:L", map)
```

--------------------------------

### Add Parameters to Method

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/MethodSpec.md

Configures the method parameters.

```java
Builder addParameter(ParameterSpec parameterSpec)
Builder addParameter(TypeName type, String name, Modifier... modifiers)
Builder addParameter(Type type, String name, Modifier... modifiers)
Builder addParameters(Iterable<ParameterSpec> parameterSpecs)
```

```java
builder.addParameter(String.class, "message")
       .addParameter(int.class, "count", Modifier.FINAL);
```

--------------------------------

### void writeTo(Path directory)

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/JavaFile.md

Writes the Java file to a directory using UTF-8 encoding.

```APIDOC
## void writeTo(Path directory)

### Description
Writes to a file system directory using UTF-8 encoding and standard package directory structure.

### Parameters
- **directory** (Path) - Required - Target directory

### Throws
- **IOException** - If directory operations fail
```

--------------------------------

### Initialize fields with custom values

Source: https://github.com/fabricmc/javapoet/blob/master/README.md

Uses the initializer method to define field values with format strings.

```java
FieldSpec android = FieldSpec.builder(String.class, "android")
    .addModifiers(Modifier.PRIVATE, Modifier.FINAL)
    .initializer("$S + $L", "Lollipop v.", 5.0d)
    .build();
```

```java
private final String android = "Lollipop v." + 5.0;
```

--------------------------------

### ClassName.get(String fullyQualifiedName)

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/ClassName.md

Creates a ClassName by parsing a fully qualified name string.

```APIDOC
## static ClassName get(String fullyQualifiedName)

### Description
Creates a ClassName by parsing a fully qualified name string.

### Parameters
- **fullyQualifiedName** (String) - Required - Full name like "java.util.List" or "java.util.Map.Entry"

### Returns
- **ClassName** - The representation of the name.
```

--------------------------------

### Configure FieldSpec with Builder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/configuration.md

Demonstrates building a private final field with Javadoc and an initializer expression.

```java
FieldSpec field = FieldSpec.builder(String.class, "value")
    .addJavadoc("The field value.\n")
    .addModifiers(Modifier.PRIVATE, Modifier.FINAL)
    .initializer("$S", "default")
    .build();
```

--------------------------------

### ClassName.get(String packageName, String simpleName, String... simpleNames)

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/ClassName.md

Creates a ClassName from a package name and a sequence of class names, useful for nested classes.

```APIDOC
## static ClassName get(String packageName, String simpleName, String... simpleNames)

### Description
Creates a ClassName from a package name and class names. The class names can represent nested classes.

### Parameters
- **packageName** (String) - Required - Package name (e.g., "java.util"); empty for default package
- **simpleName** (String) - Required - Simple class name
- **simpleNames** (String...) - Optional - Additional names for nested classes

### Returns
- **ClassName** - The representation of the fully-qualified name.
```

--------------------------------

### Enable Stack Traces for File Writing

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/errors.md

Use a try-catch block around write operations to capture and print full stack traces and error messages.

```java
try {
    javaFile.writeTo(directory);
} catch (IOException e) {
    e.printStackTrace();  // Full stack trace
    System.err.println("Details: " + e.getMessage());
}
```

--------------------------------

### MethodSpec.Builder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/configuration.md

Configuration options for building a MethodSpec instance.

```APIDOC
## MethodSpec.Builder

### Description
Configures a method or constructor definition using the MethodSpec.Builder.

### Options
- **name** (String) - Required - Method name or "<init>" for constructor
- **javadoc** (CodeBlock) - Optional - Javadoc comments
- **annotations** (List<AnnotationSpec>) - Optional - Annotations on method
- **modifiers** (Set<Modifier>) - Optional - Modifiers (PUBLIC, PRIVATE, ABSTRACT, STATIC, etc.)
- **typeVariables** (List<TypeVariableName>) - Optional - Generic type parameters
- **returnType** (TypeName) - Optional - Return type
- **parameters** (List<ParameterSpec>) - Optional - Method parameters
- **varargs** (boolean) - Optional - If true, last parameter becomes varargs
- **exceptions** (Set<TypeName>) - Optional - Checked exceptions thrown
- **code** (CodeBlock) - Optional - Method body code
- **defaultValue** (CodeBlock) - Optional - Default value (annotation members only)

### Example
```java
MethodSpec method = MethodSpec.methodBuilder("process")
    .addJavadoc("Process the input.\n")
    .addModifiers(Modifier.PUBLIC, Modifier.STATIC)
    .addTypeVariable(TypeVariableName.get("T"))
    .addParameter(String.class, "input")
    .addException(IOException.class)
    .returns(String.class)
    .addStatement("return $N.trim()", "input")
    .build();
```
```

--------------------------------

### CodeBlock.of()

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/CodeBlock.md

Creates a CodeBlock directly from a format string and arguments.

```APIDOC
## static CodeBlock of(String format, Object... args)

### Description
Creates a CodeBlock directly from a format string and arguments. Equivalent to builder().add(format, args).build().

### Parameters
- **format** (String) - Required - Format string with placeholders
- **args** (Object...) - No - Values to substitute

### Returns
Immutable CodeBlock.

### Example
```java
CodeBlock assignment = CodeBlock.of("int x = $L;", 10);
```
```

--------------------------------

### ParameterSpec.Builder.build

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/ParameterSpec.md

Finalizes the construction of the ParameterSpec.

```APIDOC
## ParameterSpec build()

### Description
Creates the immutable ParameterSpec instance.

### Returns
- ParameterSpec - Configured ParameterSpec.
```

--------------------------------

### Generate a basic class with JavaPoet

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/INDEX.md

Creates a public final class named HelloWorld using TypeSpec.

```java
TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
    .addModifiers(Modifier.PUBLIC, Modifier.FINAL)
    .addMethod(main)
    .build();
```

--------------------------------

### Create Java fields with FieldSpec

Source: https://github.com/fabricmc/javapoet/blob/master/README.md

Demonstrates defining fields using builders or helper methods and generating the corresponding class structure.

```java
FieldSpec android = FieldSpec.builder(String.class, "android")
    .addModifiers(Modifier.PRIVATE, Modifier.FINAL)
    .build();

TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
    .addModifiers(Modifier.PUBLIC)
    .addField(android)
    .addField(String.class, "robot", Modifier.PRIVATE, Modifier.FINAL)
    .build();
```

```java
public class HelloWorld {
  private final String android;

  private final String robot;
}
```

--------------------------------

### HelloWorld Class Definition

Source: https://github.com/fabricmc/javapoet/blob/master/README.md

A standard Java class definition for a HelloWorld program.

```java
package com.example.helloworld;

public final class HelloWorld {
  public static void main(String[] args) {
    System.out.println("Hello, JavaPoet!");
  }
}
```

--------------------------------

### Logging IOExceptions

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/errors.md

Standard pattern for logging file system errors during code generation.

```java
try {
    javaFile.writeTo(outputDirectory);
} catch (IOException e) {
    // Handle file system errors
    logger.error("Failed to generate code", e);
}
```

--------------------------------

### Create a constructor using constructorBuilder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/MethodSpec.md

Initializes a new constructor definition, typically used for field initialization.

```java
MethodSpec constructor = MethodSpec.constructorBuilder()
    .addModifiers(Modifier.PUBLIC)
    .addParameter(String.class, "name")
    .addStatement("this.$N = $N", "name", "name")
    .build();
```

--------------------------------

### Write JavaFile to Path and Return Path

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/JavaFile.md

Writes the file to a directory and returns the resulting Path object.

```java
Path result = javaFile.writeToPath(Paths.get("src/main/java"));
System.out.println("Wrote to: " + result);
```

--------------------------------

### ClassName.peerClass(String)

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/ClassName.md

Creates a new ClassName instance in the same package as the current instance.

```APIDOC
## ClassName.peerClass(String simpleName)

### Description
Returns a new ClassName instance for a class in the same package as this instance.

### Signature
public ClassName peerClass(String simpleName)

### Example
ClassName userRepository = ClassName.get("com.example.repository", "UserRepository");
ClassName orderRepository = userRepository.peerClass("OrderRepository");
```

--------------------------------

### Write JavaFile to Path

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/JavaFile.md

Writes the source file to a specified directory using the standard package structure.

```java
Path dir = Paths.get("src/main/java");
javaFile.writeTo(dir);
// Creates: src/main/java/com/example/HelloWorld.java
```

--------------------------------

### Configure varargs parameters

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/ParameterSpec.md

Enable varargs on the method level to treat the last parameter as a variable argument list.

```java
MethodSpec varargs = MethodSpec.methodBuilder("print")
    .addParameter(String[].class, "messages")
    .varargs(true)  // Enables varargs on the last parameter
    .returns(void.class)
    .addStatement("for ($T msg : $N) $T.out.println(msg)", 
        String.class, "messages", System.class)
    .build();
// Generates: void print(String... messages)
```

--------------------------------

### Create CodeBlock with Builder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/CodeBlock.md

Use the builder pattern to construct a CodeBlock with statements.

```java
CodeBlock block = CodeBlock.builder()
    .addStatement("int x = $L", 10)
    .build();
```

--------------------------------

### Configure ParameterSpec with Builder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/configuration.md

Use ParameterSpec.builder to define parameter types, names, Javadoc, annotations, and modifiers.

```java
ParameterSpec param = ParameterSpec.builder(String.class, "value")
    .addJavadoc("the input value\n")
    .addAnnotation(NotNull.class)
    .addModifiers(Modifier.FINAL)
    .build();
```

--------------------------------

### CodeBlock.toString()

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/CodeBlock.md

Renders the code block as a string with placeholders substituted.

```APIDOC
## String toString()

### Description
Renders the code block as a string with placeholders substituted.

### Returns
- **String** - Generated code as string.
```

--------------------------------

### Create fields with default values

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/FieldSpec.md

Defines fields with specific initial values using the initializer method.

```java
FieldSpec enabled = FieldSpec.builder(boolean.class, "enabled")
    .addModifiers(Modifier.PRIVATE)
    .initializer("$L", true)
    .build();

FieldSpec emptyString = FieldSpec.builder(String.class, "empty")
    .addModifiers(Modifier.PRIVATE, Modifier.STATIC, Modifier.FINAL)
    .initializer("$S", "")
    .build();
```

--------------------------------

### FieldSpec.Builder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/configuration.md

Configuration options for building a FieldSpec instance.

```APIDOC
## FieldSpec.Builder

### Description
Configures a field definition using the FieldSpec.Builder.

### Options
- **type** (TypeName) - Required - Field type
- **name** (String) - Required - Field name
- **javadoc** (CodeBlock) - Optional - Javadoc comments
- **annotations** (List<AnnotationSpec>) - Optional - Annotations on field
- **modifiers** (Set<Modifier>) - Optional - Modifiers (PRIVATE, FINAL, STATIC, etc.)
- **initializer** (CodeBlock) - Optional - Field initialization expression

### Example
```java
FieldSpec field = FieldSpec.builder(String.class, "value")
    .addJavadoc("The field value.\n")
    .addModifiers(Modifier.PRIVATE, Modifier.FINAL)
    .initializer("$S", "default")
    .build();
```
```

--------------------------------

### Generate methods with string returns using $S

Source: https://github.com/fabricmc/javapoet/blob/master/README.md

Demonstrates using $S within a MethodSpec to generate methods that return specific string values.

```java
public static void main(String[] args) throws Exception {
  TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
      .addModifiers(Modifier.PUBLIC, Modifier.FINAL)
      .addMethod(whatsMyName("slimShady"))
      .addMethod(whatsMyName("eminem"))
      .addMethod(whatsMyName("marshallMathers"))
      .build();

  JavaFile javaFile = JavaFile.builder("com.example.helloworld", helloWorld)
      .build();

  javaFile.writeTo(System.out);
}

private static MethodSpec whatsMyName(String name) {
  return MethodSpec.methodBuilder(name)
      .returns(String.class)
      .addStatement("return $S", name)
      .build();
}
```

--------------------------------

### FieldSpec Initializer Placeholders

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/FieldSpec.md

Supported placeholders for field initializers.

```APIDOC
## Initializer Placeholders

| Placeholder | Purpose | Example |
|-------------|---------|---------|
| `$L` | Literal value | `initializer("$L", 42)` → `42` |
| `$S` | String literal | `initializer("$S", "hello")` → `"hello"` |
| `$T` | Type reference | `initializer("$T.now()", Instant.class)` → `Instant.now()` |
| `$N` | Name reference | `initializer("$N", otherField)` → `otherField` |
| `$$` | Escaped dollar | `initializer("$$L")` → `$L` |
```

--------------------------------

### FieldSpec.Builder Methods

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/FieldSpec.md

Fluent API methods for configuring a FieldSpec instance.

```APIDOC
## Builder addJavadoc(String format, Object... args)
## Builder addJavadoc(CodeBlock block)

### Description
Adds Javadoc comments to the field.

### Returns
- Builder - Builder for chaining.

## Builder addAnnotation(AnnotationSpec annotationSpec)
## Builder addAnnotation(ClassName annotation)
## Builder addAnnotation(Class<?> annotation)
## Builder addAnnotations(Iterable<AnnotationSpec> annotationSpecs)

### Description
Adds annotations to the field.

### Returns
- Builder - Builder for chaining.

## Builder addModifiers(Modifier... modifiers)

### Description
Adds access and behavior modifiers.

### Returns
- Builder - Builder for chaining.

## Builder initializer(String format, Object... args)
## Builder initializer(CodeBlock codeBlock)

### Description
Sets the field's initialization expression.

### Parameters
- **format** (String) - Required - Initializer expression format string
- **args** (Object...) - Optional - Values to substitute
- **codeBlock** (CodeBlock) - Required - Pre-built initializer code block

### Returns
- Builder - Builder for chaining.

## FieldSpec build()

### Description
Creates the immutable FieldSpec instance.

### Returns
- FieldSpec - Configured FieldSpec.
```

--------------------------------

### Create ClassName from Package and Names

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/ClassName.md

Construct a ClassName using separate package and simple name strings, supporting nested class structures.

```java
// Top-level class
ClassName list = ClassName.get("java.util", "List");

// Nested class: java.util.Map.Entry
ClassName mapEntry = ClassName.get("java.util", "Map", "Entry");

// Deeply nested: java.util.Map.Entry.Value
ClassName entryValue = ClassName.get("java.util", "Map", "Entry", "Value");

// Default package
ClassName local = ClassName.get("", "MyClass");
```

--------------------------------

### Generate Class with Automatic Imports

Source: https://github.com/fabricmc/javapoet/blob/master/README.md

Uses $T to reference existing classes, triggering automatic import generation in the output file.

```java
MethodSpec today = MethodSpec.methodBuilder("today")
    .returns(Date.class)
    .addStatement("return new $T()", Date.class)
    .build();

TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
    .addModifiers(Modifier.PUBLIC, Modifier.FINAL)
    .addMethod(today)
    .build();

JavaFile javaFile = JavaFile.builder("com.example.helloworld", helloWorld)
    .build();

javaFile.writeTo(System.out);
```

```java
package com.example.helloworld;

import java.util.Date;

public final class HelloWorld {
  Date today() {
    return new Date();
  }
}
```

--------------------------------

### Convert JavaFile to String

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/JavaFile.md

Returns the complete source code of the JavaFile as a String.

```java
String source = javaFile.toString();
```

--------------------------------

### CodeBlock.builder()

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/CodeBlock.md

Creates a new CodeBlock builder instance for constructing code blocks.

```APIDOC
## static Builder builder()

### Description
Creates a new CodeBlock builder.

### Returns
Builder for constructing the code block.

### Example
```java
CodeBlock block = CodeBlock.builder()
    .addStatement("int x = $L", 10)
    .build();
```
```

--------------------------------

### View Type System Hierarchy

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/INDEX.md

Visual representation of the TypeName inheritance structure.

```text
TypeName (base class)
├── ClassName
├── ArrayTypeName
├── ParameterizedTypeName
├── TypeVariableName
└── WildcardTypeName
```

--------------------------------

### View Builder Class Mappings

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/INDEX.md

Mapping of core JavaPoet classes to their corresponding Builder implementations.

```text
JavaFile → JavaFile.Builder
TypeSpec → TypeSpec.Builder
MethodSpec → MethodSpec.Builder
FieldSpec → FieldSpec.Builder
ParameterSpec → ParameterSpec.Builder
AnnotationSpec → AnnotationSpec.Builder
CodeBlock → CodeBlock.Builder
```

--------------------------------

### Create an annotation builder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/TypeSpec.md

Initializes a builder for an annotation type.

```java
TypeSpec deprecated = TypeSpec.annotationBuilder("Deprecated")
    .build();
```

--------------------------------

### Handling Builder Validation Failures

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/errors.md

Demonstrates catching IllegalArgumentException when builders reject invalid configurations.

```java
// Let builders validate configuration
try {
    TypeSpec spec = TypeSpec.classBuilder("MyClass")
        .superclass(int.class)  // Primitive - will fail
        .build();
} catch (IllegalArgumentException e) {
    System.out.println("Invalid superclass: " + e.getMessage());
}
```

--------------------------------

### build

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/TypeSpec.md

Finalizes the TypeSpec instance.

```APIDOC
## TypeSpec build()

### Description
Creates the immutable TypeSpec instance from the current builder configuration.

### Returns
- **TypeSpec** - The configured TypeSpec object.
```

--------------------------------

### Add parameters to MethodSpec

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/ParameterSpec.md

Demonstrates adding parameters directly or using pre-built ParameterSpec objects.

```java
MethodSpec.methodBuilder("sum")
    .addParameter(int.class, "a")
    .addParameter(int.class, "b")
    .returns(int.class)
    .addStatement("return $N + $N", "a", "b")
    .build();

// Or add pre-built ParameterSpec objects
ParameterSpec first = ParameterSpec.builder(int.class, "first")
    .addJavadoc("first operand\n")
    .build();

ParameterSpec second = ParameterSpec.builder(int.class, "second")
    .addJavadoc("second operand\n")
    .build();

MethodSpec.methodBuilder("add")
    .addParameter(first)
    .addParameter(second)
    .returns(int.class)
    .addStatement("return $N + $N", "first", "second")
    .build();
```

--------------------------------

### Create a parameter with Javadoc

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/ParameterSpec.md

Adds documentation comments to the generated parameter.

```java
ParameterSpec timeout = ParameterSpec.builder(long.class, "timeout")
    .addJavadoc("timeout in milliseconds\n")
    .build();
```

--------------------------------

### Path writeToPath(Path directory)

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/JavaFile.md

Writes the Java file to a directory and returns the resulting Path.

```APIDOC
## Path writeToPath(Path directory)

### Description
Writes to a file system directory and returns the actual file Path written.

### Parameters
- **directory** (Path) - Required - Target directory

### Returns
- **Path** - The path to the generated .java file.
```

--------------------------------

### JavaFile Constructor

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/JavaFile.md

The constructor is private; use the static factory method builder(String packageName, TypeSpec typeSpec) to instantiate.

```java
private JavaFile(Builder builder)
```

--------------------------------

### Convert ParameterSpec to Builder

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/ParameterSpec.md

Creates a new builder instance initialized with the properties of an existing ParameterSpec.

```java
ParameterSpec modified = original.toBuilder()
    .addModifiers(Modifier.FINAL)
    .build();
```

--------------------------------

### Builder.build()

Source: https://github.com/fabricmc/javapoet/blob/master/_autodocs/api-reference/AnnotationSpec.md

Finalizes the configuration and returns an immutable AnnotationSpec instance.

```APIDOC
## Builder.build()

### Description
Creates the immutable AnnotationSpec instance based on the configured builder state.

### Returns
- **AnnotationSpec** - The configured annotation instance.
```