Document DeclaredMethodSelector

Author: marcphilipp

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/discovery/DeclaredMethodSelector.java

@@ -15,8 +15,19 @@
 
 import org.junit.platform.commons.util.Preconditions;
 import org.junit.platform.engine.DiscoverySelector;
+import org.junit.platform.engine.discovery.MethodSelector;
 
 /**
+ * Jupiter-specific selector for methods, potentially in nested classes.
+ *
+ * <p>The important difference to {@link MethodSelector} is that this selector's
+ * {@link #equals(Object)} method takes into account the selected method's
+ * {@linkplain Method#getDeclaringClass() declaring class} to support cases
+ * where a package-private method is declared in a super class in a different
+ * package and a method with the same signature is declared in a subclass. In
+ * that case both methods should be discovered because the one declared in the
+ * subclass does <em>not</em> override the one in the super class.
+ *
  * @since 6.0.1
  */
 record DeclaredMethodSelector(List<Class<?>> testClasses, Method method) implements DiscoverySelector {