Add a warning when doc string is not a string

[pirj]

Based on #2921 (comment)

The first argument should be:

For example groups:

1. a String. Either a textual description (context "in the afternoon"), or a quoted class name (describe "AdminUser")
2. a Class (describe AdminUser)
3. a NilClass (context do)

For examples:

1. a String. A textual description (it 'throws raw eggs at open source maintainers')
2. a NilClass (specify do)

For shared examples/contexts there is already an Shared example group names can only be a string, symbol or module error.

Am I missing something?

Semi-related side note: we decided not to remove a semi-related described_class in RSpec 4, even though it was previously planned.

[JonRowe]

I'm on the fence about symbols, but the rest of this is 👍

[JonRowe]

You're welcome to rewrite/remove these after this change.

[pirj]

Do you have something like

module = Module.new do
  class << self
    def math?
      true
    end
  end
end

RSpec.describe module do
  it { is_expected.to be_a Module }
  it { is_expected.to be_math }
end

or

RSpec.describe "hello" do
  it { is_expected.to be_a String }
  it { is_expected.not_to include "heaven" }
end

in mind?

[JonRowe]

A class maybe?

[pirj]

I was trying to play with "math class" initially, with "module" it's indeed less funny.

[JonRowe]

Fix rather than isolate please.

[JonRowe]

These should be removed/replaced really?

[pirj]

I'm on the fence with this, too.
On the one hand, the whole thing is to warn users when they think they add metadata (e.g. RSpec.describe :focus) which is treated as a docstring.
On the other hand, we're just issuing a warning, not hard failing, and we need some specs to prevent regressions in case we decide to rearrange things related to described_class or metadata extraction.

[JonRowe]

Yeah fair, maybe add an alias for "we expect a warning"?

[pirj]

Done

[JonRowe]

How do you feel about making this expect an error, e.g. at minimum

Suggested change

	def with_an_expected_warning
	with_isolated_stderr { yield }
	end
	def with_an_expected_warning(warning = //)
	expect { yield }.to output(warning).to_stderr
	end

This would be an actually expected warning then, optionally we could assert on the specifics?

[pirj]

Didn't work as is, had to rework as

return_value = nil
expect { return_value = yield }.to output(warning).to_stderr
return_value

and it complicates subject_value_for in memoized_helpers_spec.rb, as some usages do output and some don't.
The potential to catch unexpected warnings may not overweight the added complexity.

[JonRowe]

One last suggestion but its non blocking