From 7bde98125e7f99cab6fe80b59189561bf66fcd0e Mon Sep 17 00:00:00 2001
From: Marc-Andre Lafortune <github@marc-andre.ca>
Date: Tue, 5 May 2020 17:02:59 -0400
Subject: [PATCH] Improve documentation for Enumerator#next, next_values, peek
 and peek_values.

[DOC] [#16829]
---
 enumerator.c | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/enumerator.c b/enumerator.c
index 9632b02698..cc0cce8fae 100644
--- a/enumerator.c
+++ b/enumerator.c
@@ -81,6 +81,14 @@
  *   puts e.next   # => 3
  *   puts e.next   # raises StopIteration
  *
+ * Note that enumeration sequence by +next+, +next_values+, +peek+ and
+ * +peek_values+ do not affect other non-external
+ * enumeration methods, unless the underlying iteration method itself has
+ * side-effect, e.g. IO#each_line.
+ *
+ * Moreover, implementation typically uses fibers so performance could be
+ * slower and exception stacktraces different than expected.
+ *
  * You can use this to implement an internal iterator as follows:
  *
  *   def ext_each(e)
@@ -804,6 +812,8 @@ get_next_values(VALUE obj, struct enumerator *e)
  * internal position forward.  When the position reached at the end,
  * StopIteration is raised.
  *
+ * See class-level notes about external iterators.
+ *
  * This method can be used to distinguish <code>yield</code> and <code>yield
  * nil</code>.
  *
@@ -837,10 +847,6 @@ get_next_values(VALUE obj, struct enumerator *e)
  *   #  yield nil        [nil]            nil
  *   #  yield [1, 2]     [[1, 2]]         [1, 2]
  *
- * Note that +next_values+ does not affect other non-external enumeration
- * methods unless underlying iteration method itself has side-effect, e.g.
- * IO#each_line.
- *
  */
 
 static VALUE
@@ -894,9 +900,7 @@ ary2sv(VALUE args, int dup)
  *   p e.next   #=> 3
  *   p e.next   #raises StopIteration
  *
- * Note that enumeration sequence by +next+ does not affect other non-external
- * enumeration methods, unless the underlying iteration methods itself has
- * side-effect, e.g. IO#each_line.
+ * See class-level notes about external iterators.
  *
  */
 
@@ -926,6 +930,8 @@ enumerator_peek_values(VALUE obj)
  * doesn't move the internal position forward.  If the position is already at
  * the end, StopIteration is raised.
  *
+ * See class-level notes about external iterators.
+ *
  * === Example
  *
  *   o = Object.new
@@ -960,6 +966,8 @@ enumerator_peek_values_m(VALUE obj)
  * position forward.  If the position is already at the end, StopIteration
  * is raised.
  *
+ * See class-level notes about external iterators.
+ *
  * === Example
  *
  *   a = [1,2,3]