Update documentation why MethodFinder is needed

The only remaining test in `MethodFinderTestCase` suggests that `GetAll-
InstanceMethods` and the underlying `GetMethods` are interchangeable.

Add a reference to an existing test from another fixture, as well as a
new test, to demonstrate why this is not always the case. Update the XML
doc comment accordingly.

Author: stakx

src/Castle.Core.Tests/DynamicProxy.Tests/MethodFinderTestCase.cs

@@ -14,6 +14,7 @@
 
 namespace Castle.DynamicProxy.Tests
 {
+	using System.Linq;
 	using System.Reflection;
 
 	using Castle.DynamicProxy.Generators;
@@ -32,5 +33,37 @@ public void GetMethodsForPublicAndNonPublic()
 				typeof(object).GetMethods(BindingFlags.Instance | BindingFlags.NonPublic | BindingFlags.Public);
 			CollectionAssert.AreEquivalent(realMethods, methods);
 		}
+
+		// The test above suggests that `MethodFinder.GetAllInstanceMethods` and `Type.GetMethods`
+		// can be used interchangeably, but this is not always the case. See the test(s) below and
+		// `GenericInterfaceProxyTestCase.MethodFinderIsStable` for cases where the two methods
+		// may produce different results.
+
+#if NET5_0_OR_GREATER
+
+		[Test]
+		public void NoDuplicatesForMethodWithCovariantReturnType()
+		{
+			MethodInfo[] methods =
+				MethodFinder.GetAllInstanceMethods(typeof(Derived));
+			MethodInfo[] realMethods =
+				typeof(Derived).GetMethods(BindingFlags.Instance | BindingFlags.NonPublic | BindingFlags.Public);
+			CollectionAssert.AreNotEquivalent(realMethods, methods);
+			CollectionAssert.IsSubsetOf(subset: methods, superset: realMethods);
+			Assert.AreEqual(2, realMethods.Where(m => m.Name == nameof(Derived.Method)).Count());
+			Assert.AreEqual(1, methods.Where(m => m.Name == nameof(Derived.Method)).Count());
+		}
+
+		public abstract class Base
+		{
+			public abstract Base Method();
+		}
+
+		public abstract class Derived : Base
+		{
+			public override abstract Derived Method();
+		}
+
+#endif
 	}
 }

src/Castle.Core/DynamicProxy/Generators/MethodFinder.cs

@@ -20,8 +20,8 @@ namespace Castle.DynamicProxy.Generators
 	using System.Reflection;
 
 	/// <summary>
-	///   Returns the methods implemented by a type. Use this instead of Type.GetMethods() to work around a CLR issue
-	///   where duplicate MethodInfos are returned by Type.GetMethods() after a token of a generic type's method was loaded.
+	///   Returns the methods implemented by a type. Use this instead of Type.GetMethods to filter out duplicate MethodInfos
+	///   sometimes reported by the latter. The test suite documents cases where such duplicates may occur.
 	/// </summary>
 	internal class MethodFinder
 	{