I suggest that a WARNING that next() should not be used within a foreach loop should be included in the main body of the documentation at the top. At one time, it seems to have been there, but I spent hours trying to solve the bizarre problems that result from this combination, only to stumble on a clue to it on another site, that seem to suggest that it was originally clearly identified. If you look hard, this problem is referenced in some notes, but one doesn't expect to look there for something so basic.
