Update arg matcher misuse docs

[dtchepak]

Update after discussion at issue 35.

[zvirja]

The code snippet is very nice, but I'm afraid that we might demonstrate people anti-pattern here, as Received() should be used for this particular case. They might not remember later the exact context, but will refer like "I saw somewhere in the official docs them doing this" (happens to me often 😟 ).

Instead, we might use Do here for the exactly same purpose as we use Arg.Do() below:

...Do(x => makeCalledForId_Way1 = x.ArgAt<int>(0));

[dtchepak]

Very good point, but I think we'd need much larger changes to the docs to get better examples. Even for this we should really do .Received().Make(42) rather than catching 42 and asserting.

[zvirja]

Yes, your concern about Received() is fully valid.

I got another idea how we could prettify it. What if we change interface to the following:

public class WidgetInfo {
    public string Name { get; set; }
}

public interface IWidgetFactory {
  object Make(WidgetInfo info);
}

Then we can improve our samples as following:

// NOT OK: using an arg matcher as a value, not to specify a call:
//    widgetFactory.Make(Arg.Any<WidgetInfo>()).Returns(Arg.Any<object>());

// Instead use something like:
widgetFactory.Make(Arg.Any<WidgetInfo>()).Returns(new { Name = "Any widget" });

and

var widgetFactory = Substitute.For<IWidgetFactory>();
var subject = new Sprocket(widgetFactory);

// OK: Use arg matcher to configure a callback:
var log = new List<string>();
widgetFactory.When(x => x.Make(Arg.Any<WidgetInfo>()).Do(x => log.Add(x.Arg<WidgetInfo>().Name));

// OK: Use Arg.Do to configure a callback:
var log2 = new List<string>();
widgetFactory.Make(Arg.Do<WidgetInfo>(info => log2.Add(info.Name)));

It would be a perfectly valid scenario, when you would indeed use callbacks instead of asserting that via ugly "Arg.Is()` inspection.

[zvirja]

Update after discussion at 1

P.S. Are you using some kind of button to fill descriptions like this or it's your new life style? 😅 Now all the PR descriptions looks like there is some nasty "MR. ONE" causing all our troubles 🤣

[dtchepak]

@zvirja I've updated the example to use a log rather than something that should be using Received. It's a bit contrived, but hopefully a bit better.

The reason for Mr One is that I was trying to make it like a footnote so the long link doesn't get in the way of otherwise wrapped text, but it renders funny. Oops. 😄

Let me know if the changes look ok.

[zvirja]

@dtchepak Left you yet another idea. Feel free to accept/reject it whatever you feel suits better and go ahead with a merge 😉