gnodet-bot commented on code in PR #13538:
URL: https://github.com/apache/maven/pull/13538#discussion_r4278988456
##########
api/maven-api-core/src/main/java/org/apache/maven/api/services/Source.java:
##########
@@ -93,17 +93,19 @@ 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. The resulting path is normalized
with
+ * {@link java.nio.file.Path#normalize()}, which removes the {@code ..}
references and does not access the file
+ * system.
+ * Both forward and back slashes are only handled as separators by
+ * {@link ModelSource#resolve(ModelLocator, String)}.
Review Comment:
💡 **Nit:** Missing `<p>` before this sentence. Without it, Javadoc renders
this as a continuation of the preceding normalization paragraph. These are two
distinct points (normalization of `..` vs slash handling), so they deserve a
paragraph break:
```suggestion
* <p>
* Both forward and back slashes are only handled as separators by
* {@link ModelSource#resolve(ModelLocator, String)}.
```
--
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]
