From 8f10aa0448edc12d203fd868d690d0dbbdc9d39d Mon Sep 17 00:00:00 2001 From: Jakub Vrana Date: Tue, 21 May 2013 18:44:54 +0000 Subject: [PATCH] Standardize Generator documentation git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@330333 c90b9560-bf6c-de11-be94-00142212c4b1 --- language/generators.xml | 108 ++-------------------- language/predefined/generator.xml | 87 +++++++++++++++++ language/predefined/generator/current.xml | 52 +++++++++++ language/predefined/generator/key.xml | 58 ++++++++++++ language/predefined/generator/next.xml | 52 +++++++++++ language/predefined/generator/rewind.xml | 56 +++++++++++ language/predefined/generator/send.xml | 101 ++++++++++++++++++++ language/predefined/generator/throw.xml | 61 ++++++++++++ language/predefined/generator/valid.xml | 52 +++++++++++ language/predefined/generator/wakeup.xml | 55 +++++++++++ language/predefined/interfaces.xml | 1 + language/predefined/versions.xml | 10 ++ 12 files changed, 593 insertions(+), 100 deletions(-) create mode 100644 language/predefined/generator.xml create mode 100644 language/predefined/generator/current.xml create mode 100644 language/predefined/generator/key.xml create mode 100644 language/predefined/generator/next.xml create mode 100644 language/predefined/generator/rewind.xml create mode 100644 language/predefined/generator/send.xml create mode 100644 language/predefined/generator/throw.xml create mode 100644 language/predefined/generator/valid.xml create mode 100644 language/predefined/generator/wakeup.xml diff --git a/language/generators.xml b/language/generators.xml index 8d8a36913e..257825898f 100644 --- a/language/generators.xml +++ b/language/generators.xml @@ -200,8 +200,7 @@ foreach ($generator as $value) { This syntax may be used in conjunction with the - send() method on - Generator objects. + Generator::send method. @@ -363,108 +362,17 @@ foreach (gen_reference() as &$number) { - - - <classname>Generator</classname> objects - - - When a generator function is called for the first time, an object of the - internal Generator class is returned. This object - implements the Iterator interface in much the same - way as a forward-only iterator object would. - - - - Most methods in the Generator class have the same - semantics as the methods in the Iterator interface, - but generator objects also have one additional method: - send(). - - - + + <classname>Generator</classname> objects - Generator objects cannot be instantiated via - new. + When a generator function is called for the first time, an object of the + internal Generator class is returned. This object + implements the Iterator interface in much the same + way as a forward-only iterator object would. - - - - - - The <classname>Generator</classname> class - - -]]> - - - - - <methodname>Generator::send</methodname> - - - Generator::send allows values to be injected into - generator functions while iterating over them. The injected value will be - returned from the &yield; statement and can then be used like any other - variable within the generator function. - - - - Using <methodname>Generator::send</methodname> to inject values - -send('Hello world!'); -?> -]]> - - &example.outputs; - - - - + diff --git a/language/predefined/generator.xml b/language/predefined/generator.xml new file mode 100644 index 0000000000..900062bd11 --- /dev/null +++ b/language/predefined/generator.xml @@ -0,0 +1,87 @@ + + + + + + The Generator class + Generator + + + + +
+ &reftitle.intro; + + Generator objects are returned from generators. + + + + + Generator objects cannot be instantiated via + new. + + + +
+ + +
+ &reftitle.classsynopsis; + + + + Generator + + + + + Generator + + + + Iterator + + + + + &Methods; + + + + +
+ +
+ + &language.predefined.generator.current; + &language.predefined.generator.key; + &language.predefined.generator.next; + &language.predefined.generator.rewind; + &language.predefined.generator.send; + &language.predefined.generator.throw; + &language.predefined.generator.valid; + &language.predefined.generator.wakeup; + +
+ + diff --git a/language/predefined/generator/current.xml b/language/predefined/generator/current.xml new file mode 100644 index 0000000000..8ac4d0b94c --- /dev/null +++ b/language/predefined/generator/current.xml @@ -0,0 +1,52 @@ + + + + + + Generator::current + Get the yielded value + + + + &reftitle.description; + + public mixedGenerator::current + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the yielded value. + + + + + + + diff --git a/language/predefined/generator/key.xml b/language/predefined/generator/key.xml new file mode 100644 index 0000000000..a210a6c45b --- /dev/null +++ b/language/predefined/generator/key.xml @@ -0,0 +1,58 @@ + + + + + + Generator::key + Get the yielded key + + + + &reftitle.description; + + public mixedGenerator::key + + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the yielded key. + + + + + + + diff --git a/language/predefined/generator/next.xml b/language/predefined/generator/next.xml new file mode 100644 index 0000000000..85c26d3f6d --- /dev/null +++ b/language/predefined/generator/next.xml @@ -0,0 +1,52 @@ + + + + + + Generator::next + Resume execution of the generator + + + + &reftitle.description; + + public voidGenerator::next + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + &return.void; + + + + + + + diff --git a/language/predefined/generator/rewind.xml b/language/predefined/generator/rewind.xml new file mode 100644 index 0000000000..5d5fb04a42 --- /dev/null +++ b/language/predefined/generator/rewind.xml @@ -0,0 +1,56 @@ + + + + + + Generator::rewind + Rewind the iterator + + + + &reftitle.description; + + public voidGenerator::rewind + + + + If iteration has already begun, this will throw an exception. + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + &return.void; + + + + + + + diff --git a/language/predefined/generator/send.xml b/language/predefined/generator/send.xml new file mode 100644 index 0000000000..f100e836f4 --- /dev/null +++ b/language/predefined/generator/send.xml @@ -0,0 +1,101 @@ + + + + + + Generator::send + Send a value to the generator + + + + &reftitle.description; + + public mixedGenerator::send + mixedvalue + + + Sends the given value to the generator as the result of the yield expression + and resumes execution of the generator. + + + + Generator::send allows values to be injected into + generator functions while iterating over them. The injected value will be + returned from the &yield; statement and can then be used like any other + variable within the generator function. + + + + + &reftitle.parameters; + + + value + + + + + + + + + + + &reftitle.examples; + + + Using <methodname>Generator::send</methodname> to inject values + +send('Hello world!'); +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.returnvalues; + + Returns the yielded value. + + + + + + diff --git a/language/predefined/generator/throw.xml b/language/predefined/generator/throw.xml new file mode 100644 index 0000000000..5edb565125 --- /dev/null +++ b/language/predefined/generator/throw.xml @@ -0,0 +1,61 @@ + + + + + + Generator::throw + Throw an exception into the generator + + + + &reftitle.description; + + public voidGenerator::throw + Exceptionexception + + + + + &reftitle.parameters; + + + exception + + + + + + + + + + + &reftitle.returnvalues; + + Returns the yielded value. + + + + + + + diff --git a/language/predefined/generator/valid.xml b/language/predefined/generator/valid.xml new file mode 100644 index 0000000000..5bf15584ba --- /dev/null +++ b/language/predefined/generator/valid.xml @@ -0,0 +1,52 @@ + + + + + + Generator::valid + Check if the iterator has been closed + + + + &reftitle.description; + + public boolGenerator::valid + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns &false; if the iterator has been closed. Otherwise returns &true;. + + + + + + + diff --git a/language/predefined/generator/wakeup.xml b/language/predefined/generator/wakeup.xml new file mode 100644 index 0000000000..752c16c3e0 --- /dev/null +++ b/language/predefined/generator/wakeup.xml @@ -0,0 +1,55 @@ + + + + + + Generator::__wakeup + Serialize callback + + + + &reftitle.description; + + public voidGenerator::__wakeup + + + + Throws an exception as generators can't be serialized. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + &return.void; + + + + + + + diff --git a/language/predefined/interfaces.xml b/language/predefined/interfaces.xml index b53fb122c2..19f0305d07 100644 --- a/language/predefined/interfaces.xml +++ b/language/predefined/interfaces.xml @@ -17,6 +17,7 @@ &language.predefined.arrayaccess; &language.predefined.serializable; &language.predefined.closure; + &language.predefined.generator; diff --git a/language/predefined/versions.xml b/language/predefined/versions.xml index a1379867a7..56e704ae99 100644 --- a/language/predefined/versions.xml +++ b/language/predefined/versions.xml @@ -49,6 +49,16 @@ + + + + + + + + + +