2009/3/27 Hannes Magnusson <[email protected]>
>
> After slightly better review, could you add <classname> tags around
> "SimpleXMLIterator" in paragraphs, and use &null; rather then NULL?
> -Hannes
>
Attached is the updated patch.
I'll make you a deal; if you document another class and then submit
>
http://php.net/cvs-php, you'll have phpdoc karma as soon as Philip
> wakes up.. :)
> -Hannes
ok. :)
Juliette
Index: en/reference/spl/simplexmliterator.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/spl/simplexmliterator.xml,v
retrieving revision 1.4
diff -u -u -r1.4 simplexmliterator.xml
--- en/reference/spl/simplexmliterator.xml 23 Aug 2008 14:09:15 -0000
1.4
+++ en/reference/spl/simplexmliterator.xml 28 Mar 2009 06:00:21 -0000
@@ -10,7 +10,7 @@
<section xml:id="simplexmliterator.intro">
&reftitle.intro;
<para>
- ...
+ The SimpleXMLIterator provides recursive iteration over all nodes of a
SimpleXMLElement object.
</para>
</section>
<!-- }}} -->
Index: en/reference/spl/simplexmliterator/current.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/spl/simplexmliterator/current.xml,v
retrieving revision 1.4
diff -u -u -r1.4 current.xml
--- en/reference/spl/simplexmliterator/current.xml 20 Mar 2008 01:25:04
-0000 1.4
+++ en/reference/spl/simplexmliterator/current.xml 28 Mar 2009 06:00:21
-0000
@@ -3,7 +3,7 @@
<refentry xml:id="simplexmliterator.current"
xmlns="http://docbook.org/ns/docbook";>
<refnamediv>
<refname>SimpleXMLIterator::current</refname>
- <refpurpose>Return current SimpleXML entry</refpurpose>
+ <refpurpose>Returns the current element</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
@@ -11,9 +11,9 @@
<type>mixed</type><methodname>SimpleXMLIterator::current</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <para>
+ This method returns the current element as a
<classname>SimpleXMLIterator</classname> object or &null;.
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -24,7 +24,37 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
- The current SimpleXML entry.
+ Returns the current element as a <classname>SimpleXMLIterator</classname>
object or &null; on failure.
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Return the current element</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$xmlIterator = new SimpleXMLIterator('<books><book>PHP basics</book><book>XML
basics</book></books>');
+var_dump($xmlIterator->current());
+
+$xmlIterator->rewind(); // rewind to first element
+var_dump($xmlIterator->current());
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+NULL
+object(SimpleXMLIterator)#2 (1) {
+ [0]=>
+ string(10) "PHP basics"
+}
+]]>
+ </screen>
+ </example>
</para>
</refsect1>
Index: en/reference/spl/simplexmliterator/getchildren.xml
===================================================================
RCS file:
/repository/phpdoc/en/reference/spl/simplexmliterator/getchildren.xml,v
retrieving revision 1.4
diff -u -u -r1.4 getchildren.xml
--- en/reference/spl/simplexmliterator/getchildren.xml 20 Mar 2008 01:25:04
-0000 1.4
+++ en/reference/spl/simplexmliterator/getchildren.xml 28 Mar 2009 06:00:21
-0000
@@ -3,7 +3,7 @@
<refentry xml:id="simplexmliterator.getchildren"
xmlns="http://docbook.org/ns/docbook";>
<refnamediv>
<refname>SimpleXMLIterator::getChildren</refname>
- <refpurpose>Returns an iterator for the current entry if it is a SimpleXML
object</refpurpose>
+ <refpurpose>Returns a SimpleXMLIterator object containing the sub-elements
of the current element</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
@@ -11,9 +11,9 @@
<type>object</type><methodname>SimpleXMLIterator::getChildren</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <para>
+ This method returns a <classname>SimpleXMLIterator</classname> object
containing the sub-elements of the current
<classname>SimpleXMLIterator</classname> element.
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -24,7 +24,44 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
- An iterator for the current entry, if it is a SimpleXML object.
+ Returns a <classname>SimpleXMLIterator</classname> object containing the
sub-elements of the current element.
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Return the sub-elements of the current element</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$xml = <<<XML
+<books>
+ <book>
+ <title>PHP Basics</title>
+ <author>Jim Smith</author>
+ </book>
+</books>
+XML;
+
+$xmlIterator = new SimpleXMLIterator($xml);
+for( $xmlIterator->rewind(); $xmlIterator->valid(); $xmlIterator->next() ) {
+ foreach($xmlIterator->getChildren() as $name => $data) {
+ echo "The $name is '$data' from the class " . get_class($data) . "\n";
+ }
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+The title is 'PHP Basics' from the class SimpleXMLIterator
+The author is 'Jim Smith' from the class SimpleXMLIterator
+]]>
+ </screen>
+ </example>
</para>
</refsect1>
Index: en/reference/spl/simplexmliterator/haschildren.xml
===================================================================
RCS file:
/repository/phpdoc/en/reference/spl/simplexmliterator/haschildren.xml,v
retrieving revision 1.4
diff -u -u -r1.4 haschildren.xml
--- en/reference/spl/simplexmliterator/haschildren.xml 20 Mar 2008 01:25:04
-0000 1.4
+++ en/reference/spl/simplexmliterator/haschildren.xml 28 Mar 2009 06:00:21
-0000
@@ -3,7 +3,7 @@
<refentry xml:id="simplexmliterator.haschildren"
xmlns="http://docbook.org/ns/docbook";>
<refnamediv>
<refname>SimpleXMLIterator::hasChildren</refname>
- <refpurpose>Returns whether current entry is a SimpleXML object</refpurpose>
+ <refpurpose>Checks whether the current element has sub elements.</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
@@ -11,9 +11,9 @@
<type>bool</type><methodname>SimpleXMLIterator::hasChildren</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <para>
+ This method checks whether the current
<classname>SimpleXMLIterator</classname> element has sub-elements.
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -24,7 +24,49 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
- &true; if the current entry is a SimpleXML object, otherwise &false;
+ &true; if the current element has sub-elements, otherwise &false;
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Check whether the current element has sub-elements</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$xml = <<<XML
+<books>
+ <book>
+ <title>PHP Basics</title>
+ <author>Jim Smith</author>
+ </book>
+ <book>XML basics</book>
+</books>
+XML;
+
+$xmlIterator = new SimpleXMLIterator( $xml );
+for( $xmlIterator->rewind(); $xmlIterator->valid(); $xmlIterator->next() ) {
+ if($xmlIterator->hasChildren()) {
+ var_dump($xmlIterator->current());
+ }
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+object(SimpleXMLIterator)#2 (2) {
+ ["title"]=>
+ string(10) "PHP Basics"
+ ["author"]=>
+ string(9) "Jim Smith"
+}
+]]>
+ </screen>
+ </example>
</para>
</refsect1>
Index: en/reference/spl/simplexmliterator/key.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/spl/simplexmliterator/key.xml,v
retrieving revision 1.4
diff -u -u -r1.4 key.xml
--- en/reference/spl/simplexmliterator/key.xml 20 Mar 2008 01:25:04 -0000
1.4
+++ en/reference/spl/simplexmliterator/key.xml 28 Mar 2009 06:00:21 -0000
@@ -3,7 +3,7 @@
<refentry xml:id="simplexmliterator.key" xmlns="http://docbook.org/ns/docbook";>
<refnamediv>
<refname>SimpleXMLIterator::key</refname>
- <refpurpose>Return current SimpleXML key</refpurpose>
+ <refpurpose>Return current key</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
@@ -11,8 +11,9 @@
<type>mixed</type><methodname>SimpleXMLIterator::key</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
+ <para>
+ This method gets the XML tag name of the current element.
+ </para>
</refsect1>
@@ -24,7 +25,35 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
- The current SimpleXML key.
+ Returns the XML tag name of the element referenced by the current
<classname>SimpleXMLIterator</classname> object or &false;
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Get the current XML tag key</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$xmlIterator = new SimpleXMLIterator('<books><book>PHP basics</book><book>XML
basics</book></books>');
+
+echo var_dump($xmlIterator->key());
+$xmlIterator->rewind(); // rewind to the first element
+echo var_dump($xmlIterator->key());
+
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+bool(false)
+string(4) "book"
+]]>
+ </screen>
+ </example>
</para>
</refsect1>
Index: en/reference/spl/simplexmliterator/next.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/spl/simplexmliterator/next.xml,v
retrieving revision 1.4
diff -u -u -r1.4 next.xml
--- en/reference/spl/simplexmliterator/next.xml 20 Mar 2008 01:25:04 -0000
1.4
+++ en/reference/spl/simplexmliterator/next.xml 28 Mar 2009 06:00:21 -0000
@@ -3,7 +3,7 @@
<refentry xml:id="simplexmliterator.next"
xmlns="http://docbook.org/ns/docbook";>
<refnamediv>
<refname>SimpleXMLIterator::next</refname>
- <refpurpose>Move to next entry</refpurpose>
+ <refpurpose>Move to next element</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
@@ -11,9 +11,9 @@
<type>void</type><methodname>SimpleXMLIterator::next</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <para>
+ This method moves the <classname>SimpleXMLIterator</classname> to the next
element.
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -28,6 +28,35 @@
</para>
</refsect1>
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Move to the next element</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$xmlIterator = new SimpleXMLIterator('<books><book>PHP Basics</book><book>XML
basics</book></books>');
+$xmlIterator->rewind(); // rewind to the first element
+$xmlIterator->next();
+
+var_dump($xmlIterator->current());
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+object(SimpleXMLIterator)#2 (1) {
+ [0]=>
+ string(10) "XML basics"
+}
+]]>
+ </screen>
+ </example>
+ </para>
+ </refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
Index: en/reference/spl/simplexmliterator/rewind.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/spl/simplexmliterator/rewind.xml,v
retrieving revision 1.4
diff -u -u -r1.4 rewind.xml
--- en/reference/spl/simplexmliterator/rewind.xml 20 Mar 2008 01:25:04
-0000 1.4
+++ en/reference/spl/simplexmliterator/rewind.xml 28 Mar 2009 06:00:21
-0000
@@ -3,7 +3,7 @@
<refentry xml:id="simplexmliterator.rewind"
xmlns="http://docbook.org/ns/docbook";>
<refnamediv>
<refname>SimpleXMLIterator::rewind</refname>
- <refpurpose>Rewind SimpleXML back to the start</refpurpose>
+ <refpurpose>Rewind to the first element</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
@@ -11,9 +11,9 @@
<type>void</type><methodname>SimpleXMLIterator::rewind</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <para>
+ This method rewinds the <classname>SimpleXMLIterator</classname> to the
first element.
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -28,6 +28,34 @@
</para>
</refsect1>
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Rewind to the first element</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$xmlIterator = new SimpleXMLIterator('<books><book>PHP Basics</book><book>XML
Basics</book></books>');
+$xmlIterator->rewind();
+
+var_dump($xmlIterator->current());
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+object(SimpleXMLIterator)#2 (1) {
+ [0]=>
+ string(10) "PHP Basics"
+}
+]]>
+ </screen>
+ </example>
+ </para>
+ </refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
Index: en/reference/spl/simplexmliterator/valid.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/spl/simplexmliterator/valid.xml,v
retrieving revision 1.4
diff -u -u -r1.4 valid.xml
--- en/reference/spl/simplexmliterator/valid.xml 20 Mar 2008 01:25:04
-0000 1.4
+++ en/reference/spl/simplexmliterator/valid.xml 28 Mar 2009 06:00:21
-0000
@@ -3,7 +3,7 @@
<refentry xml:id="simplexmliterator.valid"
xmlns="http://docbook.org/ns/docbook";>
<refnamediv>
<refname>SimpleXMLIterator::valid</refname>
- <refpurpose>Check whether SimpleXML contains more entries</refpurpose>
+ <refpurpose>Check whether the current element is valid</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
@@ -11,9 +11,9 @@
<type>bool</type><methodname>SimpleXMLIterator::valid</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <para>
+ This method checks if the current element is valid after calls to rewind()
or next().
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -24,7 +24,29 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
- &true; if contains more SimpleXML entries, otherwise &false;
+ Returns &true; if the current element is valid, otherwise &false;
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Check whether the current element is valid</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$xmlIterator = new SimpleXMLIterator('<books><book>SQL Basics</book></books>');
+
+$xmlIterator->rewind(); // rewind to the first element
+echo var_dump($xmlIterator->valid()); // bool(true)
+
+$xmlIterator->next(); // advance to the next element
+echo var_dump($xmlIterator->valid()); // bool(false) because there is only one
element
+?>
+]]>
+ </programlisting>
+ </example>
</para>
</refsect1>
