Bug #17364
closedFix documentation for String#encode options
Description
(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, 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:
-
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 -
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 forCSV#new
, but even that has since changed to using the**options
style — see ruby/csv/pull/124
Files