Bug #17421: Enumerable uses overridden classes in examples

• Status: Closed
• Assignee: -
• Target version: -
• ruby -v: ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x64-mingw32]
• Backport: 2.5: UNKNOWN, 2.6: UNKNOWN, 2.7: UNKNOWN

Some method documentation in module Enumerable shows examples that cite overridden methods.

For example, method #all? is overridden in Array, but all the #all? examples in Enumerable use Arrays:

%w[ant bear cat].all? { |word| word.length >= 3 } #=> true
%w[ant bear cat].all? { |word| word.length >= 4 } #=> false
%w[ant bear cat].all?(/t/)                        #=> false
[1, 2i, 3.14].all?(Numeric)                       #=> true
[nil, true, 99].all?                              #=> false
[].all?                                           #=> true

This is true of the doc for many methods in Enumerable. Here are the overriders I've found:

all? Array
any? Array Hash
collect Array
count Array Range
cycle Array
drop Array
drop_while Array
entries Range
filter Array Struct Hash
find_index Array
first Array Range
include? Array Range Hash Set
map Array
max Array Range
member? Range Set Hash
min Array Range
minmax Array Range
none? Array
one? Array
reject Array Hash
reverse_each Array
select Array Struct Hash
sort Array
sum Array
take Array
take_while Array
to_a Array Struct Range Hash Set
to_h Array Struct Hash
to_set Set
uniq Array
zip Array

So:

• Should the Enumerable doc avoid these classes as appropriate?
• Should the overriding methods be cited and linked?

[jeremyevans0 (Jeremy Evans)]

Are there any cases where the results in the example code given in the Enumerable documentation would change if the related method was removed from the classes so that the Enumerable implementation is used?

@jeremyevans0 (Jeremy Evans), I am not aware of any such, but have not checked. I am also not aware of any difference in the call-seqs for Enumerable and an overrider, buy have not checked.

[jeremyevans0 (Jeremy Evans)]

[e-mail] (Burdette Lamar) wrote in #note-2:

@jeremyevans0 (Jeremy Evans), I am not aware of any such, but have not checked. I am also not aware of any difference in the call-seqs for Enumerable and an overrider, buy have not checked.

If there a case where the documentation does not reflect the behavior of Enumerable, that is a bug that should be fixed. However, just because Enumerable shows an example where the Enumerable method is overridden is not a bug. The purpose of the documentation is to show readers how the method works, and using arrays and hashes simplifies the documentation because readers already understand hashes and arrays. As long as the documentation reflects the behavior of Enumerable, it is fine.

The alternative would be defining custom objects that implement each for each method in the documentation just to prove to the more knowledgeable user that behavior shown comes from Enumerable and not Array/Hash. I think that would make the documentation more difficult to understand instead of easier to understand.

jeremyevans0 (Jeremy Evans) wrote in #note-3:

[e-mail] (Burdette Lamar) wrote in #note-2:

@jeremyevans0 (Jeremy Evans), I am not aware of any such, but have not checked. I am also not aware of any difference in the call-seqs for Enumerable and an overrider, buy have not checked.

If there a case where the documentation does not reflect the behavior of Enumerable, that is a bug that should be fixed. However, just because Enumerable shows an example where the Enumerable method is overridden is not a bug. The purpose of the documentation is to show readers how the method works, and using arrays and hashes simplifies the documentation because readers already understand hashes and arrays. As long as the documentation reflects the behavior of Enumerable, it is fine.

The alternative would be defining custom objects that implement each for each method in the documentation just to prove to the more knowledgeable user that behavior shown comes from Enumerable and not Array/Hash. I think that would make the documentation more difficult to understand instead of easier to understand.

Agreed.

[jeremyevans0 (Jeremy Evans)]

• Status changed from Open to Closed