From 1fb0ef23d7be0d8ecd9604fce16ee1e0842c6ef6 Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Tue, 20 Apr 2021 10:28:39 +0100
Subject: [PATCH] Fix #80942: Object iteration / Iterator: Replace duplicated
 examples with direct links

* Object iteration / Iterator: Replace duplicated examples with direct links to the appropriate sections and add cross-links.

Closes GH-517.
---
 language/generators.xml           |  10 ++
 language/oop5/iterations.xml      | 187 ++----------------------------
 language/predefined/generator.xml |   5 +
 language/predefined/iterator.xml  |   4 +
 4 files changed, 28 insertions(+), 178 deletions(-)

diff --git a/language/generators.xml b/language/generators.xml
index 8741e29dd85a..470a27046115 100644
--- a/language/generators.xml
+++ b/language/generators.xml
@@ -593,6 +593,16 @@ class LineIterator implements Iterator {
    means that the same generator can't be iterated over multiple times: the
    generator will need to be rebuilt by calling the generator function again.
   </para>
+
+  <simplesect role="seealso">
+   &reftitle.seealso;
+   <para>
+    <simplelist>
+     <member><link linkend="language.oop5.iterations">Object Iteration</link></member>
+    </simplelist>
+   </para>
+  </simplesect>
+
  </sect1>
 </chapter>
  
diff --git a/language/oop5/iterations.xml b/language/oop5/iterations.xml
index ae3260030870..7266838fb1f2 100644
--- a/language/oop5/iterations.xml
+++ b/language/oop5/iterations.xml
@@ -69,187 +69,18 @@ private => private var
   <link linkend="language.oop5.visibility">visible</link> properties that could be
   accessed.
  </para>
- <para>
-  To take it a step further, the <interfacename>Iterator</interfacename>
-  <link linkend="language.oop5.interfaces">interface</link> may be implemented.
-  This allows the object to dictate how it will be iterated and what values will
-  be available on each iteration.
- </para>
-
-  <example>
-   <title>Object Iteration implementing Iterator</title>
-   <programlisting role="php">
-<![CDATA[
-<?php
-class MyIterator implements Iterator
-{
-    private $var = array();
-
-    public function __construct($array)
-    {
-        if (is_array($array)) {
-            $this->var = $array;
-        }
-    }
-
-    public function rewind()
-    {
-        echo "rewinding\n";
-        reset($this->var);
-    }
-  
-    public function current()
-    {
-        $var = current($this->var);
-        echo "current: $var\n";
-        return $var;
-    }
-  
-    public function key() 
-    {
-        $var = key($this->var);
-        echo "key: $var\n";
-        return $var;
-    }
-  
-    public function next() 
-    {
-        $var = next($this->var);
-        echo "next: $var\n";
-        return $var;
-    }
-  
-    public function valid()
-    {
-        $key = key($this->var);
-        $var = ($key !== NULL && $key !== FALSE);
-        echo "valid: $var\n";
-        return $var;
-    }
-
-}
-
-$values = array(1,2,3);
-$it = new MyIterator($values);
-
-foreach ($it as $a => $b) {
-    print "$a: $b\n";
-}
-?>
-]]>
-   </programlisting>
-   &example.outputs;
-   <screen role="php">
-<![CDATA[
-rewinding
-valid: 1
-current: 1
-key: 0
-0: 1
-next: 2
-valid: 1
-current: 2
-key: 1
-1: 2
-next: 3
-valid: 1
-current: 3
-key: 2
-2: 3
-next:
-valid: 
-]]>
-   </screen>
-
-  </example>
 
+ <simplesect role="seealso">
+  &reftitle.seealso;
   <para>
-   The <interfacename>IteratorAggregate</interfacename>
-   <link linkend="language.oop5.interfaces">interface</link>
-   can be used as an alternative to implementing all of the
-   <interfacename>Iterator</interfacename> methods.
-   <interfacename>IteratorAggregate</interfacename> only requires the
-   implementation of a single method,
-   <methodname>IteratorAggregate::getIterator</methodname>, which should return
-   an instance of a class implementing <interfacename>Iterator</interfacename>.
+   <simplelist>
+    <member><link linkend="language.generators">Generators</link></member>
+    <member><interfacename>Iterator</interfacename></member>
+    <member><interfacename>IteratorAggregate</interfacename> </member>
+    <member><link linkend="spl.iterators">SPL Iterators</link></member>
+   </simplelist>
   </para>
-
-  <example>
-   <title>Object Iteration implementing IteratorAggregate</title>
-   <programlisting role="php">
-<![CDATA[
-<?php
-class MyCollection implements IteratorAggregate
-{
-    private $items = array();
-    private $count = 0;
-
-    // Required definition of interface IteratorAggregate
-    public function getIterator() {
-        return new MyIterator($this->items);
-    }
-
-    public function add($value) {
-        $this->items[$this->count++] = $value;
-    }
-}
-
-$coll = new MyCollection();
-$coll->add('value 1');
-$coll->add('value 2');
-$coll->add('value 3');
-
-foreach ($coll as $key => $val) {
-    echo "key/value: [$key -> $val]\n\n";
-}
-?>
-]]>
-   </programlisting>
-   &example.outputs;  
-   <screen role="php">
-<![CDATA[
-rewinding
-current: value 1
-valid: 1
-current: value 1
-key: 0
-key/value: [0 -> value 1]
-
-next: value 2
-current: value 2
-valid: 1
-current: value 2
-key: 1
-key/value: [1 -> value 2]
-
-next: value 3
-current: value 3
-valid: 1
-current: value 3
-key: 2
-key/value: [2 -> value 3]
-
-next:
-current:
-valid:
-]]>
-   </screen>
-
-  </example>
-
-  <note>
-   <para>
-    For more examples of iterators, see the
-    <link linkend="spl.iterators">SPL Extension</link>.
-   </para>
-  </note> 
-
-  <note>
-   <para>
-    <link linkend="language.generators">Generators</link> provide an
-    alternative way of defining iterators.
-   </para>
-  </note> 
+ </simplesect>
 
  </sect1>
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/generator.xml b/language/predefined/generator.xml
index c9ab409405fa..c1d0cb0aa941 100644
--- a/language/predefined/generator.xml
+++ b/language/predefined/generator.xml
@@ -52,6 +52,11 @@
 
   </section>
 
+  <section xml:id="generator.seealso">
+   &reftitle.seealso;
+   <para>See also <link linkend="language.oop5.iterations">object iteration</link>.</para>
+  </section>
+
  </partintro>
 
  &language.predefined.generator.current;
diff --git a/language/predefined/iterator.xml b/language/predefined/iterator.xml
index 5f5f552d254f..281f8f8a6ea7 100644
--- a/language/predefined/iterator.xml
+++ b/language/predefined/iterator.xml
@@ -142,6 +142,10 @@ string(17) "myIterator::valid"
    </example><!-- }}} -->
   </section>
 
+  <section xml:id="iterator.seealso">
+  &reftitle.seealso;
+   <para>See also <link linkend="language.oop5.iterations">object iteration</link>.</para>
+  </section>
 
  </partintro>