https://git.ruby-lang.org/ruby.git/commit/?id=0a7034258f

From 0a7034258f765f057ad56d1210b890d44324f904 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?=
 <shyouhei@r...>
Date: Thu, 6 May 2021 18:08:32 +0900
Subject: include/ruby/internal/intern/enum.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]
---
 include/ruby/internal/intern/enum.h | 42 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/include/ruby/internal/intern/enum.h b/include/ruby/internal/intern/enum.h
index e1d65b5..215ad82 100644
--- a/include/ruby/internal/intern/enum.h
+++ b/include/ruby/internal/intern/enum.h
@@ -26,7 +26,47 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/enum.h#L26
 RBIMPL_SYMBOL_EXPORT_BEGIN()
 
 /* enum.c */
-VALUE rb_enum_values_pack(int, const VALUE*);
+
+/**
+ * Basically identical to rb_ary_new_form_values(), except it returns something
+ * different when `argc` < 2.
+ *
+ * @param[in]  argc       Number of objects of `argv`.
+ * @param[in]  argv       Arbitrary objects.
+ * @retval     RUBY_Qnil  `argc` is zero.
+ * @retval     argv[0]    `argc` is one.
+ * @retval     otherwise  Otherwise.
+ *
+ * @internal
+ *
+ * What  is this  business?   Well,  this function  is  about `yield`'s  taking
+ * multiple values.  Consider following user-defined class:
+ *
+ * ```ruby
+ * class Foo
+ *   include Enumerable
+ *
+ *   def each
+ *     yield :q, :w, :e, :r
+ *   end
+ * end
+ *
+ * Foo.new.each_with_object([]) do |i, j|
+ *   j << i                      # ^^^ <- What to expect for `i`?
+ * end
+ * ```
+ *
+ * Here, `Foo#each_with_object` is in fact `Enumerable#each_with_object`, which
+ * doesn't know what would be yielded.  Yet, it has to take a block of arity 2.
+ * This function  is used here, to  "pack" arbitrary number of  yielded objects
+ * into one.
+ *
+ * If people want to implement their own `Enumerable#each_with_object` this API
+ * can be handy.  Though @shyouhei suspects it is relatively rare for 3rd party
+ * extension libraries  to have  such things.  Also  `Enumerable#each_entry` is
+ * basically this function exposed as a Ruby method.
+ */
+VALUE rb_enum_values_pack(int argc, const VALUE *argv);
 
 RBIMPL_SYMBOL_EXPORT_END()
 
-- 
cgit v1.1


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/