gnodet commented on issue #11381:
URL: https://github.com/apache/maven/issues/11381#issuecomment-3499861523
## Javadoc Improvements
I've also enhanced the javadoc for `SourceRoot` to make the intended
behavior more explicit and prevent future regressions.
### Enhanced `targetPath()` javadoc:
```java
/**
* {@return an explicit target path, overriding the default value}
* <p>
* The returned path is typically <strong>relative to the output
directory</strong>
* (e.g., {@code "custom-dir"} or {@code "META-INF/resources"}), but may be
absolute
* if explicitly specified as such in the project configuration.
* </p>
* ...
* <p>
* To obtain the fully resolved absolute path, use {@link
#targetPath(Project)} instead.
* </p>
*/
```
**Key clarifications:**
- Explicitly states the path is "typically **relative to the output
directory**"
- Provides concrete examples: `"custom-dir"` or `"META-INF/resources"`
- Notes that absolute paths are possible but must be explicitly specified
- Cross-references `targetPath(Project)` for obtaining the resolved absolute
path
### Enhanced `targetPath(Project)` javadoc:
```java
/**
* {@return the fully resolved absolute target path}
* <p>
* This method returns the absolute path where files from {@link
#directory()} should be copied.
* ...
* </p>
* <p>
* If {@link #targetPath()} returns:
* </p>
* <ul>
* <li>An empty {@code Optional}: returns the default output directory
* (e.g., {@code /path/to/project/target/classes})</li>
* <li>A relative path (e.g., {@code "custom-dir"}): returns the path
resolved against
* the output directory (e.g., {@code
/path/to/project/target/classes/custom-dir})</li>
* <li>An absolute path: returns that absolute path unchanged</li>
* </ul>
*/
```
**Key clarifications:**
- Clearly states this returns "the fully resolved absolute target path"
- Provides a bulleted list with concrete examples for all three cases
- Shows the relationship between `targetPath()` and `targetPath(Project)`
These improvements make the API contract crystal clear and should help
prevent similar issues in the future.
--
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]
