Explicitly call out args passed into any_instance stubs.

[dblock]

See discussion in #717 (comment).

[JonRowe]

Heh, through a weird quirk, Ruby is parsing this as head, *tail = array, so it doesn't work. Maybe we should change this example to something made up, how about:

RSpec.describe "allow_any_instance_of" do
  it 'yields the receiver to the block implementation' do
    allow_any_instance_of(Array).to receive(:final) do |array, n|
      array.slice(n * -1, n).reverse
    end

    expect([1, 2, 3].final(2)).to eq([3, 2])
  end
end

[myronmarston]

Alternately, we could use a different type than Array since arrays have splatting behavior.

[dblock]

I updated with using slice, which is already implemented as String#[start, length] and makes it a bit easier to parse.

[myronmarston]

Thanks, @dblock. My concern now is that stubbing String#slice to make it do what String#slice already does isn't at all useful. Array#shuffle, on the other hand, is non-deterministic, so the original example is the kind of thing you might actually do, in order to control it for a test.

I guess the question becomes -- is there more documentation value in having an example that includes arguments? Or is there more documentation value in having an example that's something someone might actually do?

[dblock]

You should decide that, @myronmarston. I am happy to rewrite this as any function.

The question is really what users are looking for when they read the documentation.

Personally, I never paid attention to what the example was stubbing, but always paid attention to the syntax, the macros, and the arguments. I would make all examples it 'reticulates a spline' :)

[myronmarston]

Personally, I never paid attention to what the example was stubbing, but always paid attention to the syntax, the macros, and the arguments. I would make all examples it 'reticulates a spline' :)

This is a good point. You've convinced me that while "realistic" examples might be a nice-to-have, it's far more important that we show syntax, APIs, etc.