gnodet-bot commented on code in PR #13538:
URL: https://github.com/apache/maven/pull/13538#discussion_r4278946931
##########
api/maven-api-core/src/main/java/org/apache/maven/api/services/Source.java:
##########
@@ -93,17 +93,17 @@ public interface Source {
* <p>
* The resolution strategy depends on the source type:
* <ul>
- * <li>File sources resolve against their parent directory</li>
+ * <li>Path sources resolve the relative path against their own path, so
they are meant to be used on a
+ * directory. For a file, the result is a path below that file. To
resolve against the directory
+ * containing a file, use {@link ModelSource#resolve(ModelLocator,
String)}.</li>
* <li>URL sources resolve against their base URL</li>
* <li>Other sources may not support resolution and return null</li>
* </ul>
* <p>
- * The implementation must handle:
- * <ul>
- * <li>Both forward and back slashes as path separators</li>
- * <li>Parent directory references (..)</li>
- * <li>Both file and directory targets</li>
- * </ul>
+ * A path source passes the relative path to {@link
java.nio.file.Path#resolve(String)}, so the path
+ * separators are those of the platform, and {@code ..} references are
resolved lexically in the result.
+ * Both forward and back slashes are only handled as separators by
Review Comment:
💡 **Suggestion:** "resolved lexically in the result" is technically correct
(Java uses "lexical" to mean "without I/O") but ambiguous — it could be read as
meaning `..` segments survive in the returned path. They don't: `PathSource`
always calls `path.normalize()` in its constructor, which eliminates `..`. The
test confirms this (`resolve("../other/pom.xml")` on `/tmp/x/pom.xml` →
`/tmp/x/other/pom.xml`). State the normalization explicitly:
```suggestion
* A path source passes the relative path to {@link
java.nio.file.Path#resolve(String)}, so the path
* separators are those of the platform. The result is {@linkplain
java.nio.file.Path#normalize() normalized}, so {@code ..} references are
eliminated (no filesystem I/O).
```
--
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]
