Improve output for expected argument matchers

- Add IDescribeSpecification to allow custom arg matchers to provide
  custom output for "expected to receive" entries.
- Fallback to ToString when IDescribeSpecification not implemented.
- Update code comment docs accordingly.

Closes nsubstitute#796.

src/NSubstitute/Core/Arguments/ArgumentMatcher.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics.CodeAnalysis;
 using NSubstitute.Exceptions;
 
 namespace NSubstitute.Core.Arguments;
@@ -43,6 +44,9 @@ public GenericToNonGenericMatcherProxy(IArgumentMatcher<T> matcher)
         }
 
         public bool IsSatisfiedBy(object? argument) => _matcher.IsSatisfiedBy((T?)argument!);
+
+        public override string ToString() =>
+            (_matcher as IDescribeSpecification)?.DescribeSpecification() ?? _matcher.ToString() ?? "";
     }
 
     private class GenericToNonGenericMatcherProxyWithDescribe<T> : GenericToNonGenericMatcherProxy<T>, IDescribeNonMatches
@@ -53,6 +57,9 @@ public GenericToNonGenericMatcherProxyWithDescribe(IArgumentMatcher<T> matcher)
         }
 
         public string DescribeFor(object? argument) => ((IDescribeNonMatches)_matcher).DescribeFor(argument);
+
+        public override string ToString() =>
+            (_matcher as IDescribeSpecification)?.DescribeSpecification() ?? _matcher.ToString() ?? "";
     }
 
     private class DefaultValueContainer<T>

src/NSubstitute/Core/Arguments/IArgumentMatcher.cs

@@ -1,8 +1,10 @@
 namespace NSubstitute.Core.Arguments;
 
 /// <summary>
-/// Provides a specification for arguments for use with <see ctype="Arg.Matches (IArgumentMatcher)" />.
-/// Can additionally implement <see cref="IDescribeNonMatches" /> to give descriptions when arguments do not match.
+/// Provides a specification for arguments. />.
+/// Can implement <see cref="IDescribeNonMatches" /> to give descriptions when arguments do not match.
+/// Can implement <see cref="IDescribeSpecification"/> to give descriptions of expected arguments (otherwise
+/// `ToString()` will be used for descriptions).
 /// </summary>
 public interface IArgumentMatcher
 {
@@ -14,8 +16,10 @@ public interface IArgumentMatcher
 }
 
 /// <summary>
-/// Provides a specification for arguments for use with <see ctype="Arg.Matches &lt; T &gt;(IArgumentMatcher)" />.
-/// Can additionally implement <see ctype="IDescribeNonMatches" /> to give descriptions when arguments do not match.
+/// Provides a specification for arguments. />.
+/// Can implement <see cref="IDescribeNonMatches" /> to give descriptions when arguments do not match.
+/// Can implement <see cref="IDescribeSpecification"/> to give descriptions of expected arguments (otherwise
+/// `ToString()` will be used for descriptions).
 /// </summary>
 /// <typeparam name="T">Matches arguments of type <typeparamref name="T"/> or compatible type.</typeparam>
 public interface IArgumentMatcher<T>

src/NSubstitute/Core/CallSpecification.cs

@@ -123,7 +123,9 @@ public IEnumerable<ArgumentMatchInfo> NonMatchingArguments(ICall call)
 
     public override string ToString()
     {
-        var argSpecsAsStrings = _argumentSpecifications.Select(x => x.ToString() ?? string.Empty).ToArray();
+        var argSpecsAsStrings = _argumentSpecifications.Select(x =>
+            (x as IDescribeSpecification)?.DescribeSpecification() ?? x.ToString() ?? string.Empty
+        ).ToArray();
         return CallFormatter.Default.Format(GetMethodInfo(), argSpecsAsStrings);
     }
 

src/NSubstitute/Core/IDescribeNonMatches.cs

@@ -1,5 +1,10 @@
 namespace NSubstitute.Core;
 
+/// <summary>
+/// A type that can describe how an argument does not match a required condition.
+/// Use in conjunction with <see cref="NSubstitute.Core.Arguments.IArgumentMatcher"/> to provide information about
+/// non-matches.
+/// </summary>
 public interface IDescribeNonMatches
 {
     /// <summary>
@@ -9,4 +14,4 @@ public interface IDescribeNonMatches
     /// <param name="argument"></param>
     /// <returns>Description of the non-match, or <see cref="string.Empty" /> if no description can be provided.</returns>
     string DescribeFor(object? argument);
-}
+}

src/NSubstitute/Core/IDescribeSpecification.cs

@@ -0,0 +1,15 @@
+namespace NSubstitute.Core;
+
+/// <summary>
+/// A type that can describe the required conditions to meet a specification.
+/// Use in conjunction with <see cref="NSubstitute.Core.Arguments.IArgumentMatcher"/> to provide information about
+/// what it requires to match an argument.
+/// </summary>
+public interface IDescribeSpecification {
+
+  /// <summary>
+  /// A concise description of the conditions required to match this specification.
+  /// </summary>
+  /// <returns></returns>
+  string DescribeSpecification();
+}

tests/NSubstitute.Acceptance.Specs/ArgumentMatching.cs

@@ -745,4 +745,37 @@ public void SetUp()
     {
         _something = Substitute.For<ISomething>();
     }
-}
+
+    [Test]
+    public void Should_use_ToString_to_describe_custom_arg_matcher_without_DescribesSpec()
+    {
+        var ex = Assert.Throws<ReceivedCallsException>(() =>
+        {
+            _something.Received().Add(23, ArgumentMatcher.Enqueue(new CustomMatcher()));
+        });
+        Assert.That(ex.Message, Contains.Substring("Add(23, Custom match)"));
+    }
+
+    [Test]
+    public void Should_describe_spec_for_custom_arg_matcher_when_implemented()
+    {
+        var ex = Assert.Throws<ReceivedCallsException>(() =>
+        {
+            _something.Received().Add(23, ArgumentMatcher.Enqueue(new CustomDescribeSpecMatcher()));
+        });
+        Assert.That(ex.Message, Contains.Substring("Add(23, DescribeSpec)"));
+    }
+
+    class CustomMatcher : IArgumentMatcher, IDescribeNonMatches, IArgumentMatcher<int>
+    {
+        public string DescribeFor(object argument) => "failed";
+        public bool IsSatisfiedBy(object argument) => false;
+        public bool IsSatisfiedBy(int argument) => false;
+        public override string ToString() => "Custom match";
+    }
+
+    class CustomDescribeSpecMatcher : CustomMatcher, IDescribeSpecification
+    {
+        public string DescribeSpecification() => "DescribeSpec";
+    }
+}