From 53b6f116ed5f8649ca540c38dfe0ce30619d0dd9 Mon Sep 17 00:00:00 2001
From: Jakub Vrana <vrana@php.net>
Date: Sat, 7 Jan 2012 23:06:29 +0000
Subject: [PATCH] dir is a function creating an instance of Directory class

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@321886 c90b9560-bf6c-de11-be94-00142212c4b1
---
 appendices/reserved.xml                       |   2 +-
 reference/dir/book.xml                        |   1 +
 reference/dir/directory.xml                   | 107 ++++++++++++++++++
 reference/dir/directory/close.xml             |  43 +++++++
 reference/dir/directory/read.xml              |  43 +++++++
 reference/dir/directory/rewind.xml            |  43 +++++++
 .../dir/functions/{class.dir.xml => dir.xml}  |  65 ++++++-----
 reference/dir/functions/opendir.xml           |   2 +-
 reference/filesystem/functions/is-dir.xml     |   2 +-
 9 files changed, 279 insertions(+), 29 deletions(-)
 create mode 100644 reference/dir/directory.xml
 create mode 100644 reference/dir/directory/close.xml
 create mode 100644 reference/dir/directory/read.xml
 create mode 100644 reference/dir/directory/rewind.xml
 rename reference/dir/functions/{class.dir.xml => dir.xml} (61%)

diff --git a/appendices/reserved.xml b/appendices/reserved.xml
index d949e44ca6..8366bcd181 100644
--- a/appendices/reserved.xml
+++ b/appendices/reserved.xml
@@ -314,7 +314,7 @@
       <term><classname>Directory</classname></term>
       <listitem>
        <simpara>
-        The class from which <link linkend="class.dir">dir</link> is instantiated.
+        Created by <function>dir</function>.
        </simpara>
       </listitem>
      </varlistentry>
diff --git a/reference/dir/book.xml b/reference/dir/book.xml
index 655777a54a..e971ce73aa 100644
--- a/reference/dir/book.xml
+++ b/reference/dir/book.xml
@@ -16,6 +16,7 @@
  
  &reference.dir.setup;
  &reference.dir.constants;
+ &reference.dir.directory;
  &reference.dir.reference;
 
 </book>
diff --git a/reference/dir/directory.xml b/reference/dir/directory.xml
new file mode 100644
index 0000000000..64da09528a
--- /dev/null
+++ b/reference/dir/directory.xml
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<phpdoc:classref xml:id="class.directory" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <title>The Directory class</title>
+ <titleabbrev>Directory</titleabbrev>
+
+ <partintro>
+
+<!-- {{{ Directory intro -->
+  <section xml:id="directory.intro">
+   &reftitle.intro;
+   <para>
+    Instances of <classname>Directory</classname> are created by calling the
+    <function>dir</function> function, not by the <link
+    linkend="language.oop5.basic.new">new</link> operator.
+   </para>
+  </section>
+<!-- }}} -->
+
+  <section xml:id="directory.synopsis">
+   &reftitle.classsynopsis;
+
+<!-- {{{ Synopsis -->
+   <classsynopsis>
+    <ooclass><classname>Directory</classname></ooclass>
+
+<!-- {{{ Class synopsis -->
+    <classsynopsisinfo>
+     <ooclass>
+      <classname>Directory</classname>
+     </ooclass>
+    </classsynopsisinfo>
+<!-- }}} -->
+    
+    <classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
+    <fieldsynopsis>
+     <modifier>public</modifier>
+     <type>string</type>
+     <varname linkend="directory.props.path">path</varname>
+    </fieldsynopsis>
+    <fieldsynopsis>
+     <modifier>public</modifier>
+     <type>resource</type>
+     <varname linkend="directory.props.handle">handle</varname>
+    </fieldsynopsis>
+    
+    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.directory')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
+   </classsynopsis>
+<!-- }}} -->
+
+  </section>
+
+<!-- {{{ directory properties -->
+  <section xml:id="directory.props">
+   &reftitle.properties;
+   <variablelist>
+    <varlistentry xml:id="directory.props.path">
+     <term><varname>path</varname></term>
+     <listitem>
+      <para>
+       The directory that was opened.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry xml:id="directory.props.handle">
+     <term><varname>handle</varname></term>
+     <listitem>
+      <para>
+       Can be used with other directory functions such as
+       <function>readdir</function>, <function>rewinddir</function> and
+       <function>closedir</function>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </section>
+<!-- }}} -->
+
+ </partintro>
+
+ &reference.dir.entities.directory;
+
+</phpdoc:classref>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/dir/directory/close.xml b/reference/dir/directory/close.xml
new file mode 100644
index 0000000000..72b409b763
--- /dev/null
+++ b/reference/dir/directory/close.xml
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<refentry xml:id="directory.close" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>Directory::close</refname>
+  <refpurpose>Close directory handle</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <type>void</type><methodname>Directory::close</methodname>
+   <methodparam choice="opt"><type>resource</type><parameter>dir_handle</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Same as <function>closedir</function>, only <parameter>
+   dir_handle</parameter> defaults to <varname>$this</varname>.
+  </para>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/dir/directory/read.xml b/reference/dir/directory/read.xml
new file mode 100644
index 0000000000..734da0b86c
--- /dev/null
+++ b/reference/dir/directory/read.xml
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<refentry xml:id="directory.read" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>Directory::read</refname>
+  <refpurpose>Read entry from directory handle</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <type>string</type><methodname>Directory::read</methodname>
+   <methodparam choice="opt"><type>resource</type><parameter>dir_handle</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Same as <function>readdir</function>, only <parameter>
+   dir_handle</parameter> defaults to <varname>$this</varname>.
+  </para>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/dir/directory/rewind.xml b/reference/dir/directory/rewind.xml
new file mode 100644
index 0000000000..064292273f
--- /dev/null
+++ b/reference/dir/directory/rewind.xml
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<refentry xml:id="directory.rewind" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>Directory::rewind</refname>
+  <refpurpose>Rewind directory handle</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <type>void</type><methodname>Directory::rewind</methodname>
+   <methodparam choice="opt"><type>resource</type><parameter>dir_handle</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Same as <function>rewinddir</function>, only <parameter>
+   dir_handle</parameter> defaults to <varname>$this</varname>.
+  </para>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/dir/functions/class.dir.xml b/reference/dir/functions/dir.xml
similarity index 61%
rename from reference/dir/functions/class.dir.xml
rename to reference/dir/functions/dir.xml
index 48b3a3e110..45d0dafb13 100644
--- a/reference/dir/functions/class.dir.xml
+++ b/reference/dir/functions/dir.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
 <!-- splitted from ./en/functions/dir.xml, last change in rev 1.2 -->
-<refentry xml:id="class.dir" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.dir" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>dir</refname>
   <refpurpose>Return an instance of the Directory class</refpurpose>
@@ -9,32 +9,45 @@
 
  <refsect1 role="description">
   &reftitle.description;
-  <classsynopsis>
-   <ooclass><classname>Directory</classname></ooclass>
-   <classsynopsisinfo>
-    <ooclass>
-     <classname>Directory</classname>
-    </ooclass>
-   </classsynopsisinfo>
-   <fieldsynopsis>
-    <type>string</type><varname>path</varname>
-   </fieldsynopsis>
-   <fieldsynopsis>
-    <type>resource</type><varname>handle</varname>
-   </fieldsynopsis>
-   <methodsynopsis><type>string</type><methodname>Directory::read</methodname><void/></methodsynopsis>
-   <methodsynopsis><type>void</type><methodname>Directory::rewind</methodname><void/></methodsynopsis>
-   <methodsynopsis><type>void</type><methodname>Directory::close</methodname><void/></methodsynopsis>
-  </classsynopsis>
+  <methodsynopsis>
+   <type>Directory</type><methodname>dir</methodname>
+   <methodparam><type>string</type><parameter>directory</parameter></methodparam>
+   <methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
+  </methodsynopsis>
+  
   <para>
    A pseudo-object oriented mechanism for reading a directory.  The
-   given <parameter>directory</parameter> is opened.  Two properties
-   are available once the directory has been opened.  The handle
-   property can be used with other directory functions such as
-   <function>readdir</function>, <function>rewinddir</function> and
-   <function>closedir</function>.  The path property is set to path
-   the directory that was opened.  Three methods are available:
-   read, rewind and close.
+   given <parameter>directory</parameter> is opened.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>directory</parameter></term>
+    <listitem>
+     <para>
+      Directory to open
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>context</parameter></term>
+    <listitem>
+     <para>
+      &note.context-support;
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns an instance of <classname>Directory</classname>, or &null; with
+   wrong parameters, or &false; in case of another error.
   </para>
  </refsect1>
 
@@ -44,7 +57,7 @@
    <example>
     <title><function>dir</function> example</title>
     <para>
-     Please note the fashion in which <function>dir::read</function>'s
+     Please note the fashion in which <function>Directory::read</function>'s
      return value is checked in the example below. We are explicitly
      testing whether the return value is identical to (equal to and of
      the same type as - see <link linkend="language.operators.comparison">
diff --git a/reference/dir/functions/opendir.xml b/reference/dir/functions/opendir.xml
index 91ca7523a6..4643d139fe 100644
--- a/reference/dir/functions/opendir.xml
+++ b/reference/dir/functions/opendir.xml
@@ -140,7 +140,7 @@ filename: cli : filetype: dir
    <simplelist>
     <member><function>is_dir</function></member>
     <member><function>readdir</function></member>
-    <member><link linkend="class.dir">Dir</link></member>
+    <member><function>dir</function></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/filesystem/functions/is-dir.xml b/reference/filesystem/functions/is-dir.xml
index 880f910446..c3904b20f8 100644
--- a/reference/filesystem/functions/is-dir.xml
+++ b/reference/filesystem/functions/is-dir.xml
@@ -89,7 +89,7 @@ bool(true)
   <para>
    <simplelist>
     <member><function>chdir</function></member>
-    <member><link linkend="class.dir">dir</link></member>
+    <member><function>dir</function></member>
     <member><function>opendir</function></member>
     <member><function>is_file</function></member>
     <member><function>is_link</function></member>