From: burdettelamar@... Date: 2020-12-21T22:27:16+00:00 Subject: [ruby-core:101613] [Ruby master Bug#17421] Enumerable uses overridden classes in examples Issue #17421 has been updated by burdettelamar@yahoo.com (Burdette Lamar). jeremyevans0 (Jeremy Evans) wrote in #note-3: > burdettelamar@yahoo.com (Burdette Lamar) wrote in #note-2: > > @jeremyevans0, 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. ---------------------------------------- Bug #17421: Enumerable uses overridden classes in examples https://bugs.ruby-lang.org/issues/17421#change-89399 * Author: burdettelamar@yahoo.com (Burdette Lamar) * Status: Open * Priority: Normal * 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? -- https://bugs.ruby-lang.org/ Unsubscribe: