Add new Style/ExplicitBlockArgument cop

[fatkodima]

https://rubystyle.guide/#block-argument

Consider using explicit block argument to avoid writing block literal that just passes its arguments to another block.

require 'tempfile'

# bad
def with_tmp_dir
  Dir.mktmpdir do |tmp_dir|
    Dir.chdir(tmp_dir) { |dir| yield dir }  # block just passes arguments
  end
end

# good
def with_tmp_dir(&block)
  Dir.mktmpdir do |tmp_dir|
    Dir.chdir(tmp_dir, &block)
  end
end

with_tmp_dir do |dir|
  puts "dir is accessible as a parameter and pwd is set: #{dir}"
end

[bbatsov]

I think this message is a bit confusing, as it's not very clear where is this argument supposed to be. Perhaps something like "Consider using explicit block argument in the surrounding method's signature over yield." or something along those lines.

[fatkodima]

Corrected.

[marcandre]

Please mark as unsafe (as it may change the yielding arity)

[bbatsov]

Btw, I've been thinking it'd be great if we started to add to the cop descriptions some explanations as to what exactly makes them unsafe so it's more obvious for the users.

[fatkodima]

Yes, I have the same thought and already added a line about this ))

[bbatsov]

Thanks!

[marcandre]

Btw, I've been thinking it'd be great if we started to add to the cop descriptions some explanations as to what exactly makes them unsafe so it's more obvious for the users.

Yes! With an example too...

and already added a line about this

I don't see it Oh, I see it. We need it to show in the doc and an example would help.

[fatkodima]

@marcandre https://github.com/rubocop-hq/rubocop/pull/8415/files#diff-e93280b3b31a6438c533a5f3232340d8R2913-R2914

But without an example

[bbatsov]

Going forward I think we should also add such explanation and examples to the cop description from which the documentation is generated.

[marcandre]

I created #8431