Project

General

Profile

Actions

Bug #17364

closed

Fix documentation for String#encode options

Added by tjschuck (T.J. Schuck) over 3 years ago. Updated over 3 years ago.

Status:
Closed
Assignee:
-
Target version:
-
[ruby-core:101226]

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:

  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

  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


Files

keep_options.diff (1.85 KB) keep_options.diff tjschuck (T.J. Schuck), 12/03/2020 07:38 PM
list_all_kwargs.diff (2.44 KB) list_all_kwargs.diff tjschuck (T.J. Schuck), 12/03/2020 07:38 PM
string_encode_docs.diff (1.82 KB) string_encode_docs.diff tjschuck (T.J. Schuck), 12/03/2020 08:38 PM
Actions

Also available in: Atom PDF

Like0
Like0Like0Like0Like0Like0