Skip to content

Commit f87a1b7

Browse files
yesudeepyesudeep
authored
docs(java): Add package documentation throughout and update build files (#388)
1 parent 16a241a commit f87a1b7

File tree

10 files changed

+507
-1
lines changed

10 files changed

+507
-1
lines changed

‎docs/contributing/coding_guidelines.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,23 @@ You are an expert Python developer contributing to the Google Dotprompt project.
77
- **Language**: Python.
88
- **Environment Management**: Use `uv` for packaging and environment management.
99

10-
### Libraries
10+
### Python Libraries
11+
- **JSON**: Use the built-in `json` module or `pydantic` for serialization.
12+
- **Testing**: Use `pytest` and `unittest` for testing.
13+
14+
### Java Libraries
1115
- **JSON**: Use **Jackson** for JSON parsing and serialization. Avoid Gson.
1216
- **Testing**: Use **Google Truth** (`com.google.truth.Truth`) for assertions. Use JUnit 4/5 for test runners.
1317
- **Utilities**: Use **Guava** for immutable collections and common utilities.
1418
- **Dependency Injection**: Use **Dagger** for dependency injection.
1519

20+
### Java Style Guidelines
21+
- **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`.
22+
- **Formatting**: Use `google-java-format` for code formatting.
23+
- **Javadoc**: Write comprehensive Javadoc for all public classes and methods.
24+
- **Doc Sync**: Keep Javadoc comments in sync with the code. When modifying method signatures, parameters, or return types, update the corresponding Javadoc.
25+
- **Method Chaining**: Fluent builder methods should return `this` for chaining.
26+
1627
## 2. Typing & Style
1728
- **Type Unions**: Use the pipe operator `|` (PEP 604) for union types (e.g., `int | str`) instead of `typing.Union`. Use `| None` for optional types.
1829
- **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‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ java_library(
2020
name = "helpers",
2121
srcs = [
2222
"Helpers.java",
23+
"package-info.java",
2324
],
2425
visibility = ["//visibility:public"],
2526
deps = [

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

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
/*
2+
* Copyright 2025 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*
16+
* SPDX-License-Identifier: Apache-2.0
17+
*/
18+
19+
/**
20+
* Handlebars helper functions for Dotprompt templates.
21+
*
22+
* <p>This package provides custom Handlebars helpers that enable rich template functionality in
23+
* Dotprompt. These helpers are automatically registered when creating a {@link
24+
* com.google.dotprompt.Dotprompt} instance.
25+
*
26+
* <h2>Available Helpers</h2>
27+
*
28+
* <pre>
29+
* ┌──────────────────────────────────────────────────────────────────┐
30+
* │ Dotprompt Handlebars Helpers │
31+
* ├──────────────┬───────────────────────────────────────────────────┤
32+
* │ json │ Serialize objects to JSON │
33+
* │ role │ Switch message role (user, model, system) │
34+
* │ history │ Insert conversation history │
35+
* │ section │ Delineate named sections in output │
36+
* │ media │ Embed media (images, audio, video) │
37+
* │ ifEquals │ Conditional block if values are equal │
38+
* │ unlessEquals │ Conditional block unless values are equal │
39+
* └──────────────┴───────────────────────────────────────────────────┘
40+
* </pre>
41+
*
42+
* <h2>Helper Usage Examples</h2>
43+
*
44+
* <h3>json</h3>
45+
*
46+
* <p>Serializes any object to formatted JSON. Supports an optional {@code indent} parameter.
47+
*
48+
* <pre>{@code
49+
* {{json myObject}}
50+
* {{json myObject indent=2}}
51+
* }</pre>
52+
*
53+
* <h3>role</h3>
54+
*
55+
* <p>Switches the role for subsequent content. Valid roles: user, model, system.
56+
*
57+
* <pre>{@code
58+
* {{role "system"}}You are a helpful assistant.
59+
* {{role "user"}}Hello!
60+
* }</pre>
61+
*
62+
* <h3>history</h3>
63+
*
64+
* <p>Injects conversation history at this position. History messages are passed via the render
65+
* data.
66+
*
67+
* <pre>{@code
68+
* {{role "system"}}You are a helpful assistant.
69+
* {{history}}
70+
* {{role "user"}}{{userMessage}}
71+
* }</pre>
72+
*
73+
* <h3>section</h3>
74+
*
75+
* <p>Creates a named section marker for structured output parsing.
76+
*
77+
* <pre>{@code
78+
* {{section "introduction"}}
79+
* Welcome to the tutorial.
80+
* {{section "main"}}
81+
* Main content here.
82+
* }</pre>
83+
*
84+
* <h3>media</h3>
85+
*
86+
* <p>Embeds media content with a URL and optional content type.
87+
*
88+
* <pre>{@code
89+
* {{media url="https://example.com/image.png"}}
90+
* {{media url=imageUrl contentType="image/jpeg"}}
91+
* }</pre>
92+
*
93+
* <h3>ifEquals / unlessEquals</h3>
94+
*
95+
* <p>Conditional rendering based on equality comparison.
96+
*
97+
* <pre>{@code
98+
* {{#ifEquals status "active"}}
99+
* User is active!
100+
* {{else}}
101+
* User is inactive.
102+
* {{/ifEquals}}
103+
*
104+
* {{#unlessEquals role "guest"}}
105+
* Welcome back, {{name}}!
106+
* {{/unlessEquals}}
107+
* }</pre>
108+
*
109+
* <h2>Implementation</h2>
110+
*
111+
* <p>All helpers output special marker strings that are parsed by {@link
112+
* com.google.dotprompt.parser.Parser} during rendering to produce structured {@link
113+
* com.google.dotprompt.models.Message} objects.
114+
*
115+
* <pre>
116+
* Template Helpers Parser
117+
* ┌────────────┐ ┌───────────┐ ┌──────────────────┐
118+
* │ {{role │ ──────▶ │ role() │ ──────▶ │ Parser.parse() │
119+
* │ "system"}} │ │ │ │ │
120+
* │ │ │ Returns: │ │ Produces: │
121+
* │ │ │ marker │ │ Message[role= │
122+
* │ │ │ string │ │ SYSTEM, ...] │
123+
* └────────────┘ └───────────┘ └──────────────────┘
124+
* </pre>
125+
*
126+
* @see com.google.dotprompt.helpers.Helpers
127+
* @see com.google.dotprompt.parser.Parser
128+
*/
129+
package com.google.dotprompt.helpers;

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ java_library(
5353
"ToolDefinition.java",
5454
"ToolRequestPart.java",
5555
"ToolResponsePart.java",
56+
"package-info.java",
5657
],
5758
deps = [
5859
"@maven//:com_fasterxml_jackson_core_jackson_annotations",

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

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
/*
2+
* Copyright 2025 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*
16+
* SPDX-License-Identifier: Apache-2.0
17+
*/
18+
19+
/**
20+
* Data models for Dotprompt prompts, messages, and content parts.
21+
*
22+
* <p>This package contains the core data structures used throughout Dotprompt for representing
23+
* prompts, rendered messages, and their content. These models are designed to be immutable records
24+
* for thread-safety and ease of use.
25+
*
26+
* <h2>Type Hierarchy</h2>
27+
*
28+
* <pre>
29+
* ┌─────────────────────────┐
30+
* │ Part │ (sealed interface)
31+
* │ Base for all content │
32+
* └───────────┬─────────────┘
33+
* │
34+
* ┌───────────────┬───────────┼───────────┬─────────────────┐
35+
* │ │ │ │ │
36+
* ▼ ▼ ▼ ▼ ▼
37+
* ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌────────────┐ ┌────────────────┐
38+
* │ TextPart │ │ MediaPart │ │ DataPart │ │ ToolRequest│ │ ToolResponse │
39+
* │ │ │ │ │ │ │ Part │ │ Part │
40+
* └──────────┘ └───────────┘ └──────────┘ └────────────┘ └────────────────┘
41+
* │ │ │ │ │
42+
* │ ▼ │ │ │
43+
* │ ┌───────────┐ │ │ │
44+
* │ │MediaContent│ │ │ │
45+
* │ │ url, │ │ │ │
46+
* │ │ contentType│ │ │ │
47+
* │ └───────────┘ │ │ │
48+
* │ │ │ │
49+
* └─────────────┬──────────────┴─────────────┴───────────────┘
50+
* │
51+
* ▼
52+
* ┌──────────┐
53+
* │ Message │ (role + List&lt;Part&gt; + metadata)
54+
* └────┬─────┘
55+
* │
56+
* ▼
57+
* ┌───────────────┐
58+
* │RenderedPrompt│ (config + List&lt;Message&gt;)
59+
* └───────────────┘
60+
* </pre>
61+
*
62+
* <h2>Core Types</h2>
63+
*
64+
* <h3>Content Parts</h3>
65+
*
66+
* <ul>
67+
* <li>{@link com.google.dotprompt.models.TextPart} - Plain text content
68+
* <li>{@link com.google.dotprompt.models.MediaPart} - Images, audio, video via URL
69+
* <li>{@link com.google.dotprompt.models.DataPart} - Structured data (JSON)
70+
* <li>{@link com.google.dotprompt.models.ToolRequestPart} - Tool/function call requests
71+
* <li>{@link com.google.dotprompt.models.ToolResponsePart} - Tool/function call responses
72+
* </ul>
73+
*
74+
* <h3>Messages and Prompts</h3>
75+
*
76+
* <ul>
77+
* <li>{@link com.google.dotprompt.models.Message} - A message with role, parts, and metadata
78+
* <li>{@link com.google.dotprompt.models.Prompt} - Parsed template with config
79+
* <li>{@link com.google.dotprompt.models.RenderedPrompt} - Fully rendered prompt ready for LLM
80+
* <li>{@link com.google.dotprompt.models.PromptFunction} - Compiled prompt for repeated use
81+
* </ul>
82+
*
83+
* <h3>Storage Types</h3>
84+
*
85+
* <ul>
86+
* <li>{@link com.google.dotprompt.models.PromptData} - Raw prompt data from storage
87+
* <li>{@link com.google.dotprompt.models.PromptRef} - Reference to a stored prompt
88+
* <li>{@link com.google.dotprompt.models.PartialData} - Raw partial data
89+
* <li>{@link com.google.dotprompt.models.PartialRef} - Reference to a stored partial
90+
* </ul>
91+
*
92+
* <h3>Roles</h3>
93+
*
94+
* <p>The {@link com.google.dotprompt.models.Role} enum defines message roles:
95+
*
96+
* <pre>
97+
* ┌────────┬────────────────────────────────────────────┐
98+
* │ Role │ Description │
99+
* ├────────┼────────────────────────────────────────────┤
100+
* │ USER │ Input from the user │
101+
* │ MODEL │ Output from the AI model │
102+
* │ SYSTEM │ System instructions │
103+
* │ TOOL │ Tool/function call responses │
104+
* └────────┴────────────────────────────────────────────┘
105+
* </pre>
106+
*
107+
* <h2>Usage Example</h2>
108+
*
109+
* <pre>{@code
110+
* // Create a message with mixed content
111+
* Message message = new Message(
112+
* Role.USER,
113+
* List.of(
114+
* new TextPart("Describe this image:"),
115+
* new MediaPart(new MediaContent("https://example.com/photo.jpg", "image/jpeg"))
116+
* ),
117+
* Map.of()
118+
* );
119+
*
120+
* // Work with a rendered prompt
121+
* RenderedPrompt rendered = promptFn.render(data).get();
122+
* for (Message msg : rendered.messages()) {
123+
* System.out.println(msg.role() + ": " + msg.content());
124+
* }
125+
* }</pre>
126+
*
127+
* @see com.google.dotprompt.models.Part
128+
* @see com.google.dotprompt.models.Message
129+
* @see com.google.dotprompt.models.RenderedPrompt
130+
*/
131+
package com.google.dotprompt.models;

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ java_library(
2121
srcs = [
2222
"Parser.java",
2323
"Picoschema.java",
24+
"package-info.java",
2425
],
2526
visibility = ["//visibility:public"],
2627
deps = [

0 commit comments

Comments
 (0)