diff options
| author | 卜部昌平 <[email protected]> | 2021-05-06 18:08:32 +0900 |
|---|---|---|
| committer | 卜部昌平 <[email protected]> | 2021-09-10 20:00:06 +0900 |
| commit | 0a7034258f765f057ad56d1210b890d44324f904 (patch) | |
| tree | b785f8873f071d179f3519d86d122d69d083bc2f /include/ruby/internal/intern/enum.h | |
| parent | 407c4850f19f92c703847cea1e07b3151e1cdc6e (diff) | |
include/ruby/internal/intern/enum.h: add doxygen
Must not be a bad idea to improve documents. [ci skip]
Notes
Notes:
Merged: https://github.com/ruby/ruby/pull/4815
Diffstat (limited to 'include/ruby/internal/intern/enum.h')
| -rw-r--r-- | include/ruby/internal/intern/enum.h | 42 |
1 files changed, 41 insertions, 1 deletions
diff --git a/include/ruby/internal/intern/enum.h b/include/ruby/internal/intern/enum.h index e1d65b5c9a..215ad82672 100644 --- a/include/ruby/internal/intern/enum.h +++ b/include/ruby/internal/intern/enum.h @@ -26,7 +26,47 @@ 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() |