docs(java): Add package documentation throughout and update build files

docs/contributing/coding_guidelines.md

@@ -7,12 +7,23 @@ You are an expert Python developer contributing to the Google Dotprompt project.
 - **Language**: Python.
 - **Environment Management**: Use `uv` for packaging and environment management.
 
-### Libraries
+### Python Libraries
+- **JSON**: Use the built-in `json` module or `pydantic` for serialization.
+- **Testing**: Use `pytest` and `unittest` for testing.
+
+### Java Libraries
 - **JSON**: Use **Jackson** for JSON parsing and serialization. Avoid Gson.
 - **Testing**: Use **Google Truth** (`com.google.truth.Truth`) for assertions. Use JUnit 4/5 for test runners.
 - **Utilities**: Use **Guava** for immutable collections and common utilities.
 - **Dependency Injection**: Use **Dagger** for dependency injection.
 
+### Java Style Guidelines
+- **Imports**: Always use proper imports instead of fully qualified type names. Never write `com.github.jknack.handlebars.Context` inline; instead, add an `import` statement and use `Context`.
+- **Formatting**: Use `google-java-format` for code formatting.
+- **Javadoc**: Write comprehensive Javadoc for all public classes and methods.
+- **Doc Sync**: Keep Javadoc comments in sync with the code. When modifying method signatures, parameters, or return types, update the corresponding Javadoc.
+- **Method Chaining**: Fluent builder methods should return `this` for chaining.
+
 ## 2. Typing & Style
 - **Type Unions**: Use the pipe operator `|` (PEP 604) for union types (e.g., `int | str`) instead of `typing.Union`. Use `| None` for optional types.
 - **Generics**: Use standard collection generics (PEP 585) like `list`, `dict`, `tuple` (lowercase) for type hints instead of `typing.List`, `typing.Dict`.

java/com/google/dotprompt/helpers/BUILD.bazel

@@ -20,6 +20,7 @@ java_library(
     name = "helpers",
     srcs = [
         "Helpers.java",
+        "package-info.java",
     ],
     visibility = ["//visibility:public"],
     deps = [

java/com/google/dotprompt/helpers/package-info.java

@@ -0,0 +1,129 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Handlebars helper functions for Dotprompt templates.
+ *
+ * <p>This package provides custom Handlebars helpers that enable rich template functionality in
+ * Dotprompt. These helpers are automatically registered when creating a {@link
+ * com.google.dotprompt.Dotprompt} instance.
+ *
+ * <h2>Available Helpers</h2>
+ *
+ * <pre>
+ *  ┌──────────────────────────────────────────────────────────────────┐
+ *  │                    Dotprompt Handlebars Helpers                  │
+ *  ├──────────────┬───────────────────────────────────────────────────┤
+ *  │ json         │ Serialize objects to JSON                         │
+ *  │ role         │ Switch message role (user, model, system)         │
+ *  │ history      │ Insert conversation history                       │
+ *  │ section      │ Delineate named sections in output                │
+ *  │ media        │ Embed media (images, audio, video)                │
+ *  │ ifEquals     │ Conditional block if values are equal             │
+ *  │ unlessEquals │ Conditional block unless values are equal         │
+ *  └──────────────┴───────────────────────────────────────────────────┘
+ * </pre>
+ *
+ * <h2>Helper Usage Examples</h2>
+ *
+ * <h3>json</h3>
+ *
+ * <p>Serializes any object to formatted JSON. Supports an optional {@code indent} parameter.
+ *
+ * <pre>{@code
+ * {{json myObject}}
+ * {{json myObject indent=2}}
+ * }</pre>
+ *
+ * <h3>role</h3>
+ *
+ * <p>Switches the role for subsequent content. Valid roles: user, model, system.
+ *
+ * <pre>{@code
+ * {{role "system"}}You are a helpful assistant.
+ * {{role "user"}}Hello!
+ * }</pre>
+ *
+ * <h3>history</h3>
+ *
+ * <p>Injects conversation history at this position. History messages are passed via the render
+ * data.
+ *
+ * <pre>{@code
+ * {{role "system"}}You are a helpful assistant.
+ * {{history}}
+ * {{role "user"}}{{userMessage}}
+ * }</pre>
+ *
+ * <h3>section</h3>
+ *
+ * <p>Creates a named section marker for structured output parsing.
+ *
+ * <pre>{@code
+ * {{section "introduction"}}
+ * Welcome to the tutorial.
+ * {{section "main"}}
+ * Main content here.
+ * }</pre>
+ *
+ * <h3>media</h3>
+ *
+ * <p>Embeds media content with a URL and optional content type.
+ *
+ * <pre>{@code
+ * {{media url="https://example.com/image.png"}}
+ * {{media url=imageUrl contentType="image/jpeg"}}
+ * }</pre>
+ *
+ * <h3>ifEquals / unlessEquals</h3>
+ *
+ * <p>Conditional rendering based on equality comparison.
+ *
+ * <pre>{@code
+ * {{#ifEquals status "active"}}
+ *   User is active!
+ * {{else}}
+ *   User is inactive.
+ * {{/ifEquals}}
+ *
+ * {{#unlessEquals role "guest"}}
+ *   Welcome back, {{name}}!
+ * {{/unlessEquals}}
+ * }</pre>
+ *
+ * <h2>Implementation</h2>
+ *
+ * <p>All helpers output special marker strings that are parsed by {@link
+ * com.google.dotprompt.parser.Parser} during rendering to produce structured {@link
+ * com.google.dotprompt.models.Message} objects.
+ *
+ * <pre>
+ *  Template                   Helpers                    Parser
+ *  ┌────────────┐          ┌───────────┐          ┌──────────────────┐
+ *  │ {{role     │ ──────▶  │ role()    │ ──────▶  │ Parser.parse()   │
+ *  │ "system"}} │          │           │          │                  │
+ *  │            │          │ Returns:  │          │ Produces:        │
+ *  │            │          │ marker    │          │ Message[role=    │
+ *  │            │          │ string    │          │   SYSTEM, ...]   │
+ *  └────────────┘          └───────────┘          └──────────────────┘
+ * </pre>
+ *
+ * @see com.google.dotprompt.helpers.Helpers
+ * @see com.google.dotprompt.parser.Parser
+ */
+package com.google.dotprompt.helpers;

java/com/google/dotprompt/models/BUILD.bazel

@@ -53,6 +53,7 @@ java_library(
         "ToolDefinition.java",
         "ToolRequestPart.java",
         "ToolResponsePart.java",
+        "package-info.java",
     ],
     deps = [
         "@maven//:com_fasterxml_jackson_core_jackson_annotations",

java/com/google/dotprompt/models/package-info.java

@@ -0,0 +1,131 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Data models for Dotprompt prompts, messages, and content parts.
+ *
+ * <p>This package contains the core data structures used throughout Dotprompt for representing
+ * prompts, rendered messages, and their content. These models are designed to be immutable records
+ * for thread-safety and ease of use.
+ *
+ * <h2>Type Hierarchy</h2>
+ *
+ * <pre>
+ *                        ┌─────────────────────────┐
+ *                        │         Part            │ (sealed interface)
+ *                        │  Base for all content   │
+ *                        └───────────┬─────────────┘
+ *                                    │
+ *        ┌───────────────┬───────────┼───────────┬─────────────────┐
+ *        │               │           │           │                 │
+ *        ▼               ▼           ▼           ▼                 ▼
+ *  ┌──────────┐   ┌───────────┐ ┌──────────┐ ┌────────────┐ ┌────────────────┐
+ *  │ TextPart │   │ MediaPart │ │ DataPart │ │ ToolRequest│ │ ToolResponse   │
+ *  │          │   │           │ │          │ │ Part       │ │ Part           │
+ *  └──────────┘   └───────────┘ └──────────┘ └────────────┘ └────────────────┘
+ *       │               │            │             │               │
+ *       │               ▼            │             │               │
+ *       │        ┌───────────┐       │             │               │
+ *       │        │MediaContent│      │             │               │
+ *       │        │ url,      │       │             │               │
+ *       │        │ contentType│      │             │               │
+ *       │        └───────────┘       │             │               │
+ *       │                            │             │               │
+ *       └─────────────┬──────────────┴─────────────┴───────────────┘
+ *                     │
+ *                     ▼
+ *               ┌──────────┐
+ *               │ Message  │ (role + List&lt;Part&gt; + metadata)
+ *               └────┬─────┘
+ *                    │
+ *                    ▼
+ *            ┌───────────────┐
+ *            │RenderedPrompt│ (config + List&lt;Message&gt;)
+ *            └───────────────┘
+ * </pre>
+ *
+ * <h2>Core Types</h2>
+ *
+ * <h3>Content Parts</h3>
+ *
+ * <ul>
+ *   <li>{@link com.google.dotprompt.models.TextPart} - Plain text content
+ *   <li>{@link com.google.dotprompt.models.MediaPart} - Images, audio, video via URL
+ *   <li>{@link com.google.dotprompt.models.DataPart} - Structured data (JSON)
+ *   <li>{@link com.google.dotprompt.models.ToolRequestPart} - Tool/function call requests
+ *   <li>{@link com.google.dotprompt.models.ToolResponsePart} - Tool/function call responses
+ * </ul>
+ *
+ * <h3>Messages and Prompts</h3>
+ *
+ * <ul>
+ *   <li>{@link com.google.dotprompt.models.Message} - A message with role, parts, and metadata
+ *   <li>{@link com.google.dotprompt.models.Prompt} - Parsed template with config
+ *   <li>{@link com.google.dotprompt.models.RenderedPrompt} - Fully rendered prompt ready for LLM
+ *   <li>{@link com.google.dotprompt.models.PromptFunction} - Compiled prompt for repeated use
+ * </ul>
+ *
+ * <h3>Storage Types</h3>
+ *
+ * <ul>
+ *   <li>{@link com.google.dotprompt.models.PromptData} - Raw prompt data from storage
+ *   <li>{@link com.google.dotprompt.models.PromptRef} - Reference to a stored prompt
+ *   <li>{@link com.google.dotprompt.models.PartialData} - Raw partial data
+ *   <li>{@link com.google.dotprompt.models.PartialRef} - Reference to a stored partial
+ * </ul>
+ *
+ * <h3>Roles</h3>
+ *
+ * <p>The {@link com.google.dotprompt.models.Role} enum defines message roles:
+ *
+ * <pre>
+ *  ┌────────┬────────────────────────────────────────────┐
+ *  │ Role   │ Description                                │
+ *  ├────────┼────────────────────────────────────────────┤
+ *  │ USER   │ Input from the user                        │
+ *  │ MODEL  │ Output from the AI model                   │
+ *  │ SYSTEM │ System instructions                        │
+ *  │ TOOL   │ Tool/function call responses               │
+ *  └────────┴────────────────────────────────────────────┘
+ * </pre>
+ *
+ * <h2>Usage Example</h2>
+ *
+ * <pre>{@code
+ * // Create a message with mixed content
+ * Message message = new Message(
+ *     Role.USER,
+ *     List.of(
+ *         new TextPart("Describe this image:"),
+ *         new MediaPart(new MediaContent("https://example.com/photo.jpg", "image/jpeg"))
+ *     ),
+ *     Map.of()
+ * );
+ *
+ * // Work with a rendered prompt
+ * RenderedPrompt rendered = promptFn.render(data).get();
+ * for (Message msg : rendered.messages()) {
+ *     System.out.println(msg.role() + ": " + msg.content());
+ * }
+ * }</pre>
+ *
+ * @see com.google.dotprompt.models.Part
+ * @see com.google.dotprompt.models.Message
+ * @see com.google.dotprompt.models.RenderedPrompt
+ */
+package com.google.dotprompt.models;

java/com/google/dotprompt/parser/BUILD.bazel

@@ -21,6 +21,7 @@ java_library(
     srcs = [
         "Parser.java",
         "Picoschema.java",
+        "package-info.java",
     ],
     visibility = ["//visibility:public"],
     deps = [