From 4677bf9a18a3080300a159114db0c445582b320b Mon Sep 17 00:00:00 2001
From: Mehdi Achour <didou@php.net>
Date: Sat, 30 Dec 2006 02:50:59 +0000
Subject: [PATCH] Document DOMDocumentFragment->appendXML() and
 DOMDocument->registerNodeClass(), our 2 non-DOM-standard-but-kicks-axx
 methods

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@226020 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../dom-domdocument-registernodeclass.xml     | 108 ++++++++++++++++--
 .../dom-domdocumentfragment-appendxml.xml     |  93 ++++-----------
 reference/dom/reference.xml                   |  22 +++-
 3 files changed, 145 insertions(+), 78 deletions(-)

diff --git a/reference/dom/functions/dom-domdocument-registernodeclass.xml b/reference/dom/functions/dom-domdocument-registernodeclass.xml
index 0a395b90df..37162a587d 100644
--- a/reference/dom/functions/dom-domdocument-registernodeclass.xml
+++ b/reference/dom/functions/dom-domdocument-registernodeclass.xml
@@ -1,20 +1,112 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id="function.dom-domdocument-registernodeclass">
  <refnamediv>
-  <refname>DOMDocument::registerNodeClass</refname>
+  <refname>DOMDocument->registerNodeClass()</refname>
   <refpurpose>Register extended class used to create base node type</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
-  <methodsynopsis>
-   <type>bool</type><methodname>DOMDocument::registerNodeClass</methodname>
-   <methodparam><type>string</type><parameter>baseclass</parameter></methodparam>
-   <methodparam><type>string</type><parameter>extendedclass</parameter></methodparam>
-  </methodsynopsis>
+  <classsynopsis>
+   <ooclass><classname>DOMDocument</classname></ooclass>
+   <methodsynopsis>
+    <type>bool</type><methodname>registerNodeClass</methodname>
+    <methodparam><type>string</type><parameter>baseclass</parameter></methodparam>
+    <methodparam><type>string</type><parameter>extendedclass</parameter></methodparam>
+   </methodsynopsis>
+  </classsynopsis>
 
-  &warn.undocumented.func;
+  <para>
+   This method allows you to register your own extended DOM class to be used
+   afterward by the PHP DOM extension.
+  </para>
+  <para>
+   This method is not part of the DOM standard.
+  </para>
+ </refsect1>
 
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>baseclass</parameter></term>
+     <listitem>
+      <para>
+       The DOM class that you want to extend. You can find a list of these 
+       classes in the chapter introduction.
+      </para>
+      <para>
+       Of course, you won't be able to register a class extending DOMDocument
+       but you can always start your document by instanciating your own
+       extending class.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>extendedclass</parameter></term>
+     <listitem>
+      <para>
+       Your extended class name. If &null; is provided, any previously 
+       registered class extending <parameter>baseclass</parameter> will
+       be removed.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.success;
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Adding a new method to DOMElement to ease our code</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+class myElement extends DOMElement {
+   function appendElement($name) { 
+      return $this->appendChild(new myElement($name));
+   }
+}
+
+class myDocument extends DOMDocument {
+   function setRoot($name) { 
+      return $this->appendChild(new myElement($name));
+   }
+}
+
+$doc = new myDocument();
+$doc->registerNodeClass('DOMElement', 'myElement');
+
+// From now on, adding an element to another costs only one method call ! 
+$root = $doc->setRoot('root');
+$child = $root->appendElement('child');
+$child->setAttribute('foo', 'bar');
+
+echo $doc->saveXML();
+
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen role="xml">
+<![CDATA[
+<?xml version="1.0"?>
+<root><child foo="bar"/></root>
+]]>
+    </screen>
+   </example>
+  </para>
  </refsect1>
 
 </refentry>
diff --git a/reference/dom/functions/dom-domdocumentfragment-appendxml.xml b/reference/dom/functions/dom-domdocumentfragment-appendxml.xml
index b16d4534b2..f4e7eacbf9 100644
--- a/reference/dom/functions/dom-domdocumentfragment-appendxml.xml
+++ b/reference/dom/functions/dom-domdocumentfragment-appendxml.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- Generated by xml_proto.php v2.3. Found in /scripts directory of phpdoc. -->
-<refentry id="function.dom-domdocumentfragment.appendxml">
+<refentry id="function.dom-domdocumentfragment-appendxml">
  <refnamediv>
   <refname>DOMDocumentFragment->appendXML()</refname>
-  <refpurpose>Append XML data</refpurpose>
+  <refpurpose>Append raw XML data</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
@@ -15,9 +15,18 @@
     <methodparam><type>string</type><parameter>data</parameter></methodparam>
    </methodsynopsis>
   </classsynopsis>
-
-  &warn.undocumented.func;
-
+  <para>
+   Appends raw XML data to a DOMDocumentFragment. 
+  </para>
+  <para>
+   This method is not part of the DOM standard. It was created as a simplier
+   approach for appending an XML DocumentFragment in a DOMDocument.
+  </para>
+  <para>
+   If you want to stick to the standards, you will have to create a temporary
+   DOMDocument with a dummy root and then loop through the child nodes of the
+   root of your XML data to append them. 
+  </para>
  </refsect1>
  <refsect1 role="parameters">
   &reftitle.parameters;
@@ -41,85 +50,33 @@
   </para>
  </refsect1>
 
- <!-- Use when ERRORS exist
- <refsect1 role="errors">
-  &reftitle.errors;
-  <para>
-   When does this function throw E_* level errors, or exceptions?
-  </para>
- </refsect1>
- -->
-
-
- <!-- Use when a CHANGELOG exists
- <refsect1 role="changelog">
-  &reftitle.changelog;
-  <para>
-   <informaltable>
-    <tgroup cols="2">
-     <thead>
-      <row>
-       <entry>&Version;</entry>
-       <entry>&Description;</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Enter the PHP version of change here</entry>
-       <entry>Description of change</entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </informaltable>
-  </para>
- </refsect1>
- -->
-
-
- <!-- Use when examples exist
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
    <example>
-    <title>A <function>DOMDocumentFragment::appendXML</function> example</title>
-    <para>
-     Any text that describes the purpose of the example, or
-     what goes on in the example should go here (inside the
-     <example> tag, not out
-    </para>
+    <title>Appending XML data to your document</title>
     <programlisting role="php">
 <![CDATA[
 <?php
-if ($anexample === true) {
-    echo 'Use the PEAR Coding Standards';
-}
+$doc = new DOMDocument();
+$doc->loadXML("<root/>");
+$f = $doc->createDocumentFragment();
+$f->appendXML("<foo>text</foo><bar>text2</bar>");
+$doc->documentElement->appendChild($f);
+echo $doc->saveXML(); 
 ?>
 ]]>
     </programlisting>
     &example.outputs;
-    <screen>
+    <screen role="xml">
 <![CDATA[
-Use the PEAR Coding Standards
+<?xml version="1.0"?>
+<root><foo>text</foo><bar>text2</bar></root>
 ]]>
     </screen>
    </example>
   </para>
  </refsect1>
- -->
-
-
- <!-- Use when adding See Also links
- <refsect1 role="seealso">
-  &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function></function></member>
-    <member>Or <link linkend="somethingelse">something else</link></member>
-   </simplelist>
-  </para>
- </refsect1>
- -->
-
 
 </refentry>
 
diff --git a/reference/dom/reference.xml b/reference/dom/reference.xml
index 455280ffce..9b19e550be 100644
--- a/reference/dom/reference.xml
+++ b/reference/dom/reference.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.26 $ -->
+<!-- $Revision: 1.27 $ -->
 <!-- Purpose: xml -->
 <!-- Membership: bundled, external -->
 
@@ -262,6 +262,9 @@
       <listitem>
        <para><xref linkend='function.dom-domdocument-relaxngvalidatesource' /> - Performs relaxNG validation on the document</para>
       </listitem>
+      <listitem>
+       <para><xref linkend='function.dom-domdocument-registernodeclass' /> - Register extended class used to create base node type (not DOM standard)</para>
+      </listitem>
       <listitem>
        <para><xref linkend='function.dom-domdocument-save' /> - Dumps the internal XML tree back into a file</para>
       </listitem>
@@ -447,6 +450,21 @@
      </section>
     </section>
 
+    <section id='dom.class.domdocumentfragment'>
+     <title><classname>DOMDocumentFragment</classname></title>
+     <para>
+      Extends <classname>DOMNode</classname>.
+     </para>
+     <section id='dom.class.domdocumentfragment.methods'>
+      &reftitle.methods;
+      <itemizedlist>
+      <listitem>
+       <para><xref linkend='function.dom-domdocumentfragment-appendxml' /> - Append raw XML data (not DOM standard)</para>
+      </listitem>
+      </itemizedlist>
+     </section>
+    </section>
+
      <section id='dom.class.domdocumenttype'>
      <title><classname>DOMDocumentType</classname></title>
      <para>
@@ -1277,7 +1295,7 @@
     </para>
     <para>
      <example>
-      <title>chapter.xml</title>
+      <title>book.xml</title>
       <programlisting role="xml">
 <![CDATA[
 <?xml version="1.0" encoding="iso-8859-1"?>