gnodet commented on PR #11394:
URL: https://github.com/apache/maven/pull/11394#issuecomment-3502344456
## Further Javadoc Refinements for Maximum Clarity
I've pushed another update that significantly refines the Maven 4 API
javadoc to make it even more explicit and clear. The documentation now leaves
no ambiguity about how `targetPath` handling works.
### Key Enhancements
#### 1. **SourceRoot.targetPath()** - The Storage Method
**New sections added:**
- **"Important" callout**: Explicitly states this returns the path AS
CONFIGURED (no resolution)
- **"Return Value Semantics"**: Detailed explanation of what each return
value means:
- Empty Optional → files go to output directory root
- Relative Path → intended to be resolved against output directory
(resolution happens in `targetPath(Project)`)
- Absolute Path → used as-is
- **"Usage Guidance"**: Clear instructions for three audiences:
- Maven 4 API consumers: use `targetPath(Project)` instead
- Maven 3 compatibility layer: use this method for legacy plugins
- Implementers: store path as-is, don't resolve at storage time
**Why this matters**: Makes it crystal clear that this method is for
STORAGE, not RESOLUTION.
#### 2. **SourceRoot.targetPath(Project)** - The Resolution Method
**New sections added:**
- **"Purpose"**: Explicitly states this is THE method for path resolution
- **Detailed algorithm**: Step-by-step explanation with all edge cases
- **Comprehensive table**: Shows concrete examples with:
- Configuration input (what `targetPath()` returns)
- Output directory (from `getOutputDirectory()`)
- Final result (what this method returns)
- Explanation of each case
- **"Relationship to targetPath()"**: Explains the storage vs resolution
separation
- **"Implementation Note"**: Shows equivalent code for clarity
**Example from the table:**
| Configuration | Output Directory | Result | Explanation |
|--------------|------------------|--------|-------------|
| `Optional.empty()` | `/home/user/myproject/target/classes` |
`/home/user/myproject/target/classes` | No explicit path → use output directory
|
| `Optional.of(Path.of("META-INF"))` | `/home/user/myproject/target/classes`
| `/home/user/myproject/target/classes/META-INF` | Relative path → resolve
against output directory |
| `Optional.of(Path.of("/tmp/custom"))` |
`/home/user/myproject/target/classes` | `/tmp/custom` | Absolute path → use
as-is |
**Why this matters**: Developers can see exactly how each case is handled
with concrete examples.
#### 3. **Project.getOutputDirectory()** - The Base Directory Provider
**New sections added:**
- **"Purpose"**: Explains this provides the base for path resolution
- **Comprehensive table**: Maps scope to directory with build configuration
and contents
- **"Role in SourceRoot Path Resolution"**: Shows concrete examples:
- Main resources with `targetPath="META-INF"` → `target/classes/META-INF`
- Test resources with `targetPath="test-data"` →
`target/test-classes/test-data`
- **Expanded Maven 3 compatibility**: Includes actual XML configuration
example showing how maven-resources-plugin uses this
- **Code examples**: Demonstrates usage for all three scopes
**Why this matters**: Makes the connection between this method and
`SourceRoot.targetPath(Project)` explicit.
### HTML5 Compliance
Fixed javadoc generation errors by replacing deprecated HTML attributes:
- ❌ `<table border="1" cellpadding="5" cellspacing="0">`
- ✅ `<table class="striped">`
Javadoc now builds cleanly without errors.
### Documentation Philosophy
The refined documentation follows a clear pattern:
1. **Separation of Concerns**:
- `targetPath()` = STORAGE (returns as configured)
- `targetPath(Project)` = RESOLUTION (returns absolute path)
- `getOutputDirectory()` = BASE PROVIDER (provides resolution base)
2. **Audience-Specific Guidance**:
- Maven 4 API consumers know to use `targetPath(Project)`
- Maven 3 compatibility layer knows to use `targetPath()`
- Implementers know to store without resolving
3. **Concrete Examples**:
- Tables with actual paths
- XML configuration snippets
- Code examples
4. **Explicit Contracts**:
- What each method returns
- When to use which method
- How methods relate to each other
### Verification
✅ Javadoc builds successfully without errors
✅ All three methods have coherent, cross-referenced documentation
✅ Maven 3 compatibility guarantees are explicit
✅ Maven 4 API semantics are clear
The documentation now provides complete clarity on the targetPath handling
design, making it easy for developers to understand and use the API correctly.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
