2009/3/27 Hannes Magnusson <hannes.magnus...@gmail.com> > > 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>