gnodet commented on PR #11394:
URL: https://github.com/apache/maven/pull/11394#issuecomment-3502316697
## Latest Update: Enhanced Javadoc for API Clarity
I've just pushed an update that significantly improves the documentation to
clarify the Maven 4 API semantics while making the Maven 3 backward
compatibility guarantees explicit.
### What Changed
Enhanced javadoc for three key methods:
1. **`SourceRoot.targetPath()`** - Now clearly documents:
- Relative paths are resolved relative to the output directory (not
project basedir)
- Absolute paths are used as-is
- Empty/null means files go to output directory root
- Explicitly states Maven 3 compatibility is maintained
2. **`SourceRoot.targetPath(Project)`** - Now includes:
- Step-by-step resolution algorithm
- Concrete examples with actual paths
- Cross-references to related methods
3. **`Project.getOutputDirectory(ProjectScope)`** - Now clarifies:
- Returns directory for both compiled classes AND resources
- Its role in SourceRoot targetPath resolution
- Maven 3 compatibility semantics
4. **`DefaultSourceRoot` constructor from Resource** - Now documents:
- targetPath is stored as-is (not resolved against basedir)
- baseDir parameter is only used for source directory resolution
- How this preserves Maven 3.x behavior
### Why This Matters
The enhanced documentation makes it crystal clear that:
- **For Maven 4 API users**: Use `targetPath(Project)` to get the fully
resolved absolute path
- **For Maven 3 compatibility**: The `targetPath()` method returns the
relative path that plugins expect
- **For implementers**: The separation of concerns between storage and
resolution is now explicit
### Implementation Verification
The documentation now matches the actual implementation:
✅ `DefaultSourceRoot` stores `targetPath` as-is (relative or absolute)
✅ `ConnectedResource` extracts `targetPath` as a relative path string
✅ maven-resources-plugin receives the relative path and resolves it (Maven 3
behavior)
✅ Maven 4 API consumers can use `targetPath(Project)` for absolute paths
See the detailed explanation in [this comment on
#11381](https://github.com/apache/maven/issues/11381#issuecomment-3502314999)
for the complete design rationale.
--
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]
