Improve docs for "Custom Matcher from scratch"

[elado]

When creating a custom matcher and using it with a mock argument expectation, the === method should also be defined, otherwise, the match will fail.

Example:

expect(instance).to receive(:method).with(a_matcher(1))

Documentation here - http://rubydoc.info/github/rspec/rspec-expectations/RSpec/Matchers
Under Custom Matcher from scratch

Add this code to the class:

class BeInZone
  def initialize(expected)
    @expected = expected
  end

  # ...

  alias === matches?

  # ...
end

Alternatively, rspec-mocks should see if this is a matcher and use matches?.

[myronmarston]

A better approach is to include RSpec::Matchers::Composable; it defines the === alias and provides some other functionality to help use the matcher in composable fashion.

I agree the docs could be improved, though....want to open a PR to improve it?

[cupakromer]

We may want to link to the matcher protocol that was add in #567.

@elado thanks for reporting this, does lib/rspec/matchers/matcher_protocol.rb provide the details you seek?

[myronmarston]

We may want to link to the matcher protocol that was add in #567.

That would be good. I also think the examples should be updated to show that we recommend including RSpec::Matchers::Composable as it's intended to be mixed into every matcher class so that it supports the full composability features of matchers in RSpec 3.