Document eval_gemfile

[sambostock]

Warning
This PR and rubygems/rubygems#6292 are mutually exclusive. At most one of them should be merged.
I personally think documenting it is the better approach, but I have opened rubygems/rubygems#6292 as the alternative.

What was the end-user problem that led to this PR?

eval_gemfile is a useful method used across many projects, but it is not explicitly documented. On the other hand, it isn't explicitly marked as undocumented via something like # :nodoc:. This leads to confusion as to whether it should be used or not, as in rails/rails#47033

What was your diagnosis of the problem?

We should clearly mark the method as part of the public API, or private API.

What is your fix for the problem, implemented in this PR?

This adds documentation for eval_gemfile and how it can be used in one's Gemfile.

Why did you choose this fix out of the possible options?

The alternative is to mark it as private using something a magic comment:

def eval_gemfile # :nodoc:

However, as this is in use by many projects, my personal preference is to see it become public. Searching GitHub for usage turns up examples such as the following:

• Loading the main gemfile from alternate gemfiles, used to test against specific gem versions
  • https://github.com/Shopify/maintenance_tasks/blob/6a95544479979ea38151b72b9d2cb99e8e381c67/gemfiles/rails_6_0.gemfile#L5
  • https://github.com/socketry/falcon/blob/a0e70287ba5168545cab00b980c01a1a6fa0f5ac/gems/rack-v1.rb#L3
• Loading a per-dev gemfile that isn't tracked in version control
  • https://github.com/rubocop/rubocop/blob/3a542a96fb59c254d68348c54e04af8fdcab7b4e/Gemfile#L30-L31
  • https://github.com/dry-rb/dry-validation/blob/ce18224a1c05a8fe78c1a729b804a12acdebbbb5/Gemfile#L5
  • https://github.com/rom-rb/rom/blob/7fb82cf7ffa86805d9c5499a4ecc64d5d3c20f14/Gemfile#L7
  • The debated usage in Rails, mentioned above (see Use eval_gemfile to read .Gemfile rails/rails#47033 & Revert "Use eval_gemfile to read .Gemfile" rails/rails#47098)
• Other usage (didn't investigate)
  • https://github.com/rspec/rspec-rails/blob/40261bb72875c00a6e4a0ca2ac697b660d4e8d9c/example_app_generator/generate_app.rb#L47-L48
  • https://github.com/oracle/truffleruby/blob/dd8609b306c1558e6071d4e76424da82e1481325/lib/mri/bundler/injector.rb#L35

This PR serves to start the discussion, so we can take a clear stance one way or the other. I've also opened rubygems/rubygems#6292, if we prefer to mark it as :nodoc: instead, although I personally would prefer to document it.

[sambostock]

This comment was surfaced on the PR in Rails, but I'm not sure if it still applies, as it is from 2017, and it's possible things have changed since them (Bundler's stance, as well as community usage).

[simi]

This comment was surfaced on the PR in Rails, but I'm not sure if it still applies, as it is from 2017, and it's possible things have changed since them (Bundler's stance, as well as community usage).

As I mentioned in Rails PR, I have asked other RubyGems maintainers and mainly @deivid-rodriguez mentioned it was never intended to be public API.

[ekohl]

For what it's worth, dependabot supports eval_gemfile but only with fixed strings. So you can't interpolate or use variables (such as glob bundler.d/*.rb). That does work just fine with bundler but a if this becomes a formal API, it would be nice to consider that use case too so third party tooling like dependabot can also support it