@jeremyevans I see you have reviewed other contributions to documentation. It looks like I can't request a review from you on this PR via the interface.

I'd actually support making it clearer that only changes to the object, not assignment to the variable, have lasting effects. The reason is that there are similar methods (the most prominent being inject/reduce) where assignments actually have an effect. So making the reader aware of the fact that there is a difference seems important.

The reason is that there are similar methods (the most prominent being inject/reduce) where assignments actually have an effect.

Assignments to argument(s) can never have effects outside the block.
You may have placed an assignment at the end of block?

In general, that assignment in a local scope has no effect outside is elementary and very common in modern programing languages, except for special cases such as assignment operators in C++.
It may be worth to be described somewhere (doc/syntax/assignment.rdoc ?) for beginners.

There are 2 reasons I refer to documentation:

1. to gain an initial understanding of what an object is capable of
2. because something is not working the way I expect and I'm having difficulty figuring out exactly where the problem might be

This was an example of that second case. I've been programming in Ruby for about a decade, and in this instance -- against the backdrop of the code in context -- the "beginner error" that I'm making wasn't obvious. (It is, of course, much easier to see in hindsight, especially when posted in minimal form.)

But the question is worth asking: is there a reason that Enumerable's documentation (of all things) shouldn't be more accessible to a beginner audience? It seems like something a beginner would run into fairly quickly.

There is every reason to close this bug with the comment "well, Ian is just an idiot sometimes and he shouldn't be". But I opened this PR to express the manner in which I found the documentation lacking.

But the question is worth asking: is there a reason that Enumerable's documentation (of all things) shouldn't be more accessible to a beginner audience? It seems like something a beginner would run into fairly quickly.

@ianfixes - This is an elementary level information about the assignments which should be covered in another place if hasn't already been as this behavior is nothing different than just local variable assignment, like so;

def foo(var)
  var = :zoo
end

var = :bar
foo(var)

puts var # bar

Respectfully, I think you are missing my point.

We agree that there is no need to put beginner-level instruction on the nature of assignment in ruby into the documentation of each_with_object.

What I'm suggesting is that the documentation cover a pitfall which is specific to this function: if you need to change the value of the "arbitrary object", be sure to use an object method (like .replace) and not an assignment operator.

What I'm suggesting is that the documentation cover a pitfall which is specific to this function: if you need to change the value of the "arbitrary object", be sure to use an object method (like .replace) and not an assignment operator.

I think the others consider that it is a part of “the nature of assignment” and not specific to this method.

@jeremyevans what do you think of the updated text?

@jeremyevans what do you think of the updated text?

I think it's a bit long. A bigger issue I see is with the call_seq, which doesn't make it obvious that the argument passed to the method is the same as the second argument passed to the block.

Maybe:

 *  call-seq:
 *    enum.each_with_object(obj) { |element, obj| ... }  ->  obj
 *    enum.each_with_object(obj)                         ->  an_enumerator
 *
 *  For each element in <i>enum</i>, yield the element and the
 *  argument to the method. Returns the argument.

I think the others consider that it is a part of “the nature of assignment” and not specific to this method.

Again, respectfully, you are talking past me.

When I read the Enumerable documentation, all of the methods that take a block fall into one of 3 categories:

Would you agree that one of these things is not like the others?

 *    enum.each_with_object(obj) { |element, obj| ... }  ->  obj

I considered doing this, but thought that it would be confusing (in the sense that it looks like shadowing). Can you confirm if that's OK here?

Let me see about shortening the text.

 *    enum.each_with_object(obj) { |element, obj| ... }  ->  obj

I considered doing this, but thought that it would be confusing (in the sense that it looks like shadowing). Can you confirm if that's OK here?

I think in this case it is fine, and properly shows that the method parameter, second block argument, and return argument are all the same object. However, other committers may have different opinions.

I think @nobu's point is not about each_with_object versus other enumerable methods. It's about your issue being caused by the nature of assignment/scope in general:

def foo(bar)
  bar = 2
end
bar = 3
foo(bar)
bar # 3, not 2

You are stating this is a pitfall specific to each_with_object. I disagree with that. I agree with @nobu that it is not specific to each_with_object, it's just how assignment/scope work in Ruby, as shown in the above example.

Might as well show all my work. I'm working from the existing documentation for inject:

inject(initial) { |memo, obj| block } → obj

If you specify a block, then for each element in enum the block is passed an accumulator value (memo) and the element. If you specify a symbol instead, then each element in the collection will be passed to the named method of memo. In either case, the result becomes the new value for memo. At the end of the iteration, the final value of memo is the return value for the method.

This documentation uses obj twice, but one is the element and one is the return value -- I'd rather not do the same thing here.
Removing the part about symbols (which doesn't apply to each_with_object) and tweaking the existing variable names, I get this:

each_with_object(obj) { |(*args), memo_obj| ... } -> obj
each_with_object(initial) { |(*args), initial_obj| ... } -> initial

For each element in enum, the block is passed the element (*args) and initial as an accumulator value (initial_obj). At the end of the iteration, the final value of initial is the return value for the method.

Is that better? I feel like inject and each_with_object have enough in common that the descriptions should contain similar language, is that the wrong starting point?

Might as well show all my work. I'm working from the existing documentation for inject:

inject(initial) { |memo, obj| block } → obj
If you specify a block, then for each element in enum the block is passed an accumulator value (memo) and the element. If you specify a symbol instead, then each element in the collection will be passed to the named method of memo. In either case, the result becomes the new value for memo. At the end of the iteration, the final value of memo is the return value for the method.

This documentation uses obj twice, but one is the element and one is the return value -- I'd rather not do the same thing here.

The reason this is bad in inject is that the block argument obj and the return value obj represent two different objects. I would change the block argument from obj to element, but that's out of scope for this discussion on each_with_object.

Removing the part about symbols (which doesn't apply to each_with_object) and tweaking the existing variable names, I get this:

each_with_object(obj) { |(*args), memo_obj| ... } -> obj
each_with_object(initial) { |(*args), initial_obj| ... } -> initial
For each element in enum, the block is passed the element (*args) and initial as an accumulator value (initial_obj). At the end of the iteration, the final value of initial is the return value for the method.

Is that better? I feel like inject and each_with_object have enough in common that the descriptions should contain similar language, is that the wrong starting point?

No, I don't think that is better. It misses the primary point of my recommendation, which is to reflect in the call-seq that the object passed to the method is yielded as the second argument to the block and also the return value.

I don't think inject and each_with_index are sufficiently similar such that the documentation of one is required to be based on the other.

It sounds like 2 maintainer-acceptable options are being proposed for this text:

@jeremyevans version

enum.each_with_object(obj) { |(*args), obj| ... } -> obj
enum.each_with_object(obj) -> an_enumerator
For each element in enum, the block is passed the element (*args) and an accumulator value (obj). At the end of the iteration, the final value of obj is the return value for the method.

vs

@nobu version

enum.each_with_object(obj) { |(*args), memo_obj| ... } -> obj
enum.each_with_object(obj) -> an_enumerator
For each element in enum, the block is passed the element and an accumulator value (memo_obj), which is a reference to the initially given object (obj). At the end of the iteration, obj is returned

Which one should I go with?

Bumping this, please let me know if I should wait more than a week before bumping it again