From c009db40ee3473744729a391355abf44c3778d44 Mon Sep 17 00:00:00 2001
From: Guillaume Nodet <gnodet@gmail.com>
Date: Wed, 23 Aug 2023 10:01:16 +0200
Subject: [PATCH] Fix doc

---
 .../maven/model/building/ModelSource3.java    | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/maven-model-builder/src/main/java/org/apache/maven/model/building/ModelSource3.java b/maven-model-builder/src/main/java/org/apache/maven/model/building/ModelSource3.java
index 02e13bfaeb11..d48320ae59c2 100644
--- a/maven-model-builder/src/main/java/org/apache/maven/model/building/ModelSource3.java
+++ b/maven-model-builder/src/main/java/org/apache/maven/model/building/ModelSource3.java
@@ -27,20 +27,29 @@
 public interface ModelSource3 extends ModelSource2 {
     /**
      * Returns model source identified by a path relative to this model source POM. Implementation <strong>MUST</strong>
-     * be able to accept <code>relPath</code> parameter values that
+     * accept <code>relPath</code> parameter values that
      * <ul>
      * <li>use either / or \ file path separator</li>
      * <li>have .. parent directory references</li>
-     * <li>point either at file or directory, in the latter case the provided {@code ModelLocator} will be used
-     * to find the POM file, else if no locator is provided, a file named 'pom.xml' needs to be used by the
-     * requested model source.</li>
+     * <li>point either at file or directory</li>
      * </ul>
+     * If the given path points at a directory, the provided {@code ModelLocator} will be used
+     * to find the POM file, else if no locator is provided, a file named 'pom.xml' needs to be
+     * used by the requested model source.
      *
-     * @param relPath is the path of the requested model source relative to this model source POM.
+     * @param locator locator used to actually locate the pom file.
+     * @param relPath path of the requested model source relative to this model source POM.
      * @return related model source or <code>null</code> if no such model source.
      */
     ModelSource3 getRelatedSource(ModelLocator locator, String relPath);
 
+    /**
+     * When using a ModelSource3, the method with a {@code ModelLocator} argument should
+     * be used instead.
+     *
+     * @deprecated use {@link #getRelatedSource(ModelLocator, String)} instead
+     */
+    @Deprecated
     default ModelSource3 getRelatedSource(String relPath) {
         return getRelatedSource(null, relPath);
     }