From 693ce6af0a3c73ae6927ea67e990cd7f778eaac7 Mon Sep 17 00:00:00 2001 From: Jeremy Evans Date: Thu, 29 Jul 2021 08:10:20 -0700 Subject: [PATCH] Update documentation for ruby2_keywords Point out that the method should be used for backwards compatibility with code prior to Ruby 3.0 instead of Ruby 2.7. It's still needed in Ruby 2.7. It isn't needed in Ruby 3.0, as the methods using it could switch to delegating both positional and keyword arguments. Add a link to the www.ruby-lang.org web page that goes into detail describing when and how ruby2_keywords should be used. --- vm_method.c | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/vm_method.c b/vm_method.c index 182d42dc1a..1950fb1f9d 100644 --- a/vm_method.c +++ b/vm_method.c @@ -2165,14 +2165,13 @@ rb_mod_private(int argc, VALUE *argv, VALUE module) * methods. * * This should only be used for methods that delegate keywords to another - * method, and only for backwards compatibility with Ruby versions before - * 2.7. + * method, and only for backwards compatibility with Ruby versions before 3.0. + * See https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/ + * for details on why +ruby2_keywords+ exists and when and how to use it. * * This method will probably be removed at some point, as it exists only - * for backwards compatibility. As it does not exist in Ruby versions - * before 2.7, check that the module responds to this method before calling - * it. Also, be aware that if this method is removed, the behavior of the - * method will change so that it does not pass through keywords. + * for backwards compatibility. As it does not exist in Ruby versions before + * 2.7, check that the module responds to this method before calling it: * * module Mod * def foo(meth, *args, &block) @@ -2180,6 +2179,10 @@ rb_mod_private(int argc, VALUE *argv, VALUE module) * end * ruby2_keywords(:foo) if respond_to?(:ruby2_keywords, true) * end + * + * However, be aware that if the +ruby2_keywords+ method is removed, the + * behavior of the +foo+ method using the above approach will change so that + * the method does not pass through keywords. */ static VALUE