From 80cbff1fc0a43445b88a199eeadc17d10cec39fd Mon Sep 17 00:00:00 2001
From: Daniel Egeberg <degeberg@php.net>
Date: Wed, 24 Feb 2010 12:23:28 +0000
Subject: [PATCH] Should be the last fix to SimpleXMLElement::children().
 Grammar fixes, documented parameters, added additional example.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@295463 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../simplexml/simplexmlelement/children.xml   | 56 +++++++++++++++++--
 1 file changed, 50 insertions(+), 6 deletions(-)

diff --git a/reference/simplexml/simplexmlelement/children.xml b/reference/simplexml/simplexmlelement/children.xml
index cf312177de..144972659e 100644
--- a/reference/simplexml/simplexmlelement/children.xml
+++ b/reference/simplexml/simplexmlelement/children.xml
@@ -13,12 +13,12 @@
    <methodsynopsis>
     <type>SimpleXMLElement</type><methodname>children</methodname>
     <methodparam choice="opt"><type>string</type><parameter>ns</parameter></methodparam>
-    <methodparam choice="opt"><type>bool</type><parameter>is_prefix</parameter></methodparam>
+    <methodparam choice="opt"><type>bool</type><parameter>is_prefix</parameter><initializer>false</initializer></methodparam>
    </methodsynopsis>
   </classsynopsis>
   <para>
-   This method finds the children of the element of which it is a member. The result
-   follows normal iteration rules.
+   This method finds the children of an element. The result follows normal
+   iteration rules.
   </para>
   &simplexml.iteration;
  </refsect1>
@@ -31,6 +31,7 @@
      <term><parameter>ns</parameter></term>
      <listitem>
       <para>
+       An <acronym>XML</acronym> namespace.
       </para>
      </listitem>
     </varlistentry>
@@ -38,7 +39,10 @@
      <term><parameter>is_prefix</parameter></term>
      <listitem>
       <para>
-       Default to &false;
+       If <parameter>ns_prefix</parameter> is &true;,
+       <parameter>ns</parameter> will be regarded as a namespace
+       <acronym>URL</acronym>. If &false;, <parameter>ns</parameter> will be
+       regarded as a prefix.
       </para>
      </listitem>
     </varlistentry>
@@ -50,7 +54,7 @@
   &reftitle.returnvalues;
   <para>
    Returns a <classname>SimpleXMLElement</classname> element, whether the node 
-   have children or not.
+   has children or not.
   </para>
  </refsect1>
 
@@ -118,6 +122,46 @@ foreach ($xml->children() as $second_gen) {
 <![CDATA[
 The person begot a son who begot a daughter; The person
 begot a daughter who begot a son; and that son begot a son
+]]>
+    </screen>
+   </example>
+   <example>
+    <title>Using namespaces</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$xml = '<example xmlns:foo="my.foo.urn">
+  <foo:a>Apple</foo:a>
+  <foo:b>Banana</foo:b>
+  <c>Cherry</c>
+</example>';
+
+$sxe = new SimpleXMLElement($xml);
+
+$kids = $sxe->children('foo');
+var_dump(count($kids));
+
+$kids = $sxe->children('foo', TRUE);
+var_dump(count($kids));
+
+$kids = $sxe->children('my.foo.urn');
+var_dump(count($kids));
+
+$kids = $sxe->children('my.foo.urn', TRUE);
+var_dump(count($kids));
+
+$kids = $sxe->children();
+var_dump(count($kids));
+?>
+]]>
+    </programlisting>
+    <screen>
+<![CDATA[
+int(0)
+int(2)
+int(2)
+int(0)
+int(1)
 ]]>
     </screen>
    </example>
@@ -129,7 +173,7 @@ begot a daughter who begot a son; and that son begot a son
 
   <simpara>
    <methodname>SimpleXMLElement::children</methodname> returns a node 
-   object no matter if the current node have children or not. Use
+   object no matter if the current node has children or not. Use
    <function>count</function> on the return value to see if there are any
    children.
   </simpara>