From: tj@... Date: 2020-12-03T19:44:46+00:00 Subject: [ruby-core:101226] [Ruby master Bug#17364] Fix documentation for String#encode options Issue #17364 has been reported by tjschuck (T.J. Schuck). ---------------------------------------- Bug #17364: Fix documentation for String#encode options https://bugs.ruby-lang.org/issues/17364 * Author: tjschuck (T.J. Schuck) * Status: Open * Priority: Normal * Backport: 2.5: UNKNOWN, 2.6: UNKNOWN, 2.7: UNKNOWN ---------------------------------------- (Everything below is written about `String#encode`, but it also applies to `String#encode!` ��� only referring to `encode` for brevity.) The current signature for `String#encode` is `str.encode(dst_encoding, src_encoding [, options] )`, and the docs below say: > The `options` Hash gives details for conversion... However, starting in Ruby 2.7, if you pass the options as a Hash, you get the warning "Using the last argument as keyword parameters is deprecated", and in Ruby 3.0-preview1, it raises "ArgumentError (wrong number of arguments (given 3, expected 0..2))". In the ultimately called `str_transcode`, you can see that the argument format is `"02:"` in [transcode.c:L2760](https://github.com/ruby/ruby/blob/04b96fc322fe6547d2587f5ccbe0a835af93e48d/transcode.c#L2760), i.e. they're actually keyword arguments. Since there are so many keyword arguments that don't have "obvious" defaults to document in the method signature itself, attached are two proposed patches for how to fix the docs: 1. `keep_options.diff` uses a similar approach to the one used in, e.g., `CSV#filter`, using `**options` in the signature and then specifying that those are intended to be keyword arguments�������see [csv.rb:997-1042](https://github.com/ruby/ruby/blob/04b96fc322fe6547d2587f5ccbe0a835af93e48d/lib/csv.rb#L997-L1042) 2. `list_all_kwargs.diff` is probably the more strictly "correct" option, but definitely more unwieldy. You can see a similar usage to this in the current Ruby 2.7 docs for `CSV#new`, but even that has since changed to using the `**options` style �����see [ruby/csv/pull/124](https://github.com/ruby/csv/pull/124) ---Files-------------------------------- keep_options.diff (1.85 KB) list_all_kwargs.diff (2.44 KB) -- https://bugs.ruby-lang.org/ Unsubscribe: