Improve dom_import_simplexml() docs (GH-3882)

* Fix dom_import_simplexml() return type (see <php/php-src#16489>)
* Fix return values section, too
* Update function and parameter descriptions
* Clarify aliasing/view behavior and add example

Co-authored-by: Niels Dossche <[email protected]>

Author: cmb69

reference/dom/functions/dom-import-simplexml.xml

@@ -11,14 +11,15 @@
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>DOMElement</type><methodname>dom_import_simplexml</methodname>
+   <type class="union"><type>DOMAttr</type><type>DOMElement</type></type><methodname>dom_import_simplexml</methodname>
    <methodparam><type>object</type><parameter>node</parameter></methodparam>
   </methodsynopsis>
   <para>
-   This function takes the node <parameter>node</parameter> of class
-   <link linkend="ref.simplexml">SimpleXML</link> and makes it into a
-   <classname>DOMElement</classname> node. This new object can then be used
-   as a native <classname>DOMElement</classname> node. 
+   This function takes the given attribute or element <parameter>node</parameter> (a
+   <classname>SimpleXMLElement</classname> instance) and creates a
+   <classname>DOMAttr</classname> or <classname>DOMElement</classname> node, repectively.
+   The new <classname>DOMNode</classname> refers to the same underlying XML node
+   as the <classname>SimpleXMLElement</classname>.
   </para>
  </refsect1>
  <refsect1 role="parameters">
@@ -29,7 +30,7 @@
      <term><parameter>node</parameter></term>
      <listitem>
       <para>
-       The <classname>SimpleXMLElement</classname> node.
+       The attribute or element node to import (a <classname>SimpleXMLElement</classname> instance).
       </para>
      </listitem>
     </varlistentry>
@@ -39,7 +40,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   The <classname>DOMElement</classname> node added.
+   The <classname>DOMAttr</classname> or <classname>DOMElement</classname>.
   </para>
  </refsect1>
 
@@ -95,6 +96,38 @@ echo $dom->saveXML();
 ?>
 ]]>
    </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+<?xml version="1.0"?>
+<books><book><title>blah</title></book></books>
+]]>
+   </screen>
+  </example>
+  <example>
+   <title>Import SimpleXML into DOM and modify SimpleXML through DOM</title>
+   <simpara>
+    Error handling omitted for brevity.
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$sxe = simplexml_load_string('<books><book><title>blah</title></book></books>');
+$elt = dom_import_simplexml($sxe);
+$elt->setAttribute("foo", "bar");
+echo $sxe->asXML();
+
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+<?xml version="1.0"?>
+<books foo="bar"><book><title>blah</title></book></books>
+]]>
+   </screen>
   </example>
  </refsect1>
  <refsect1 role="seealso">