Fix description of EngineDiscoveryListener in class-level Javadoc

This commit also moves the note about test engines needing to publish
discovery events from EngineDiscoveryListener to TestEngine.discover().

Closes #4880

(cherry picked from commit da0e19b)

Author: sbrannen

junit-platform-engine/src/main/java/org/junit/platform/engine/EngineDiscoveryListener.java

@@ -16,19 +16,16 @@
 import org.apiguardian.api.API;
 
 /**
- * {@code EngineDiscoveryListener} contains {@link TestEngine} access to the
- * information necessary to discover tests and containers.
+ * {@code EngineDiscoveryListener} defines the API which enables a {@link TestEngine}
+ * to publish information about events that occur during test discovery.
  *
  * <p>All methods in this interface have empty <em>default</em> implementations.
  * Concrete implementations may therefore override one or more of these methods
  * to be notified of the selected events.
  *
- * <p>The methods declared in this interface <em>should</em> be called by
- * each {@link TestEngine} during test discovery. However, since this interface
- * was only added in 1.6, older engines might not yet do so.
- *
  * @since 1.6
  * @see EngineDiscoveryRequest#getDiscoveryListener()
+ * @see org.junit.platform.launcher.LauncherDiscoveryListener
  */
 @API(status = STABLE, since = "1.10")
 public interface EngineDiscoveryListener {

junit-platform-engine/src/main/java/org/junit/platform/engine/TestEngine.java

@@ -67,6 +67,10 @@ public interface TestEngine {
 	 * must be used to create unique IDs for children of the root's descriptor
 	 * by calling {@link UniqueId#append}.
 	 *
+	 * <p>Furthermore, implementations must publish events about test discovery
+	 * via the supplied {@link EngineDiscoveryRequest#getDiscoveryListener()
+	 * EngineDiscoveryListener}.
+	 *
 	 * @param discoveryRequest the discovery request; never {@code null}
 	 * @param uniqueId the unique ID to be used for this test engine's
 	 * {@code TestDescriptor}; never {@code null}