From 314d5d831f51c844aa0ede08962d99e3c861d18e Mon Sep 17 00:00:00 2001
From: Joris van de Sande <joris@php.net>
Date: Tue, 27 Jul 2010 18:46:35 +0000
Subject: [PATCH] - Documented arguments, returnvalues and erros for
 ReflectionClass methods: getFileName, newInstance, newInstanceArgs and
 __toString - Added example for ReflectionClass method __toString

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@301619 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../reflectionclass/getfilename.xml           | 10 +--
 .../reflectionclass/newinstance.xml           | 24 +++--
 .../reflectionclass/newinstanceargs.xml       | 20 ++++-
 .../reflection/reflectionclass/tostring.xml   | 89 +++++++++++++++++--
 4 files changed, 122 insertions(+), 21 deletions(-)

diff --git a/reference/reflection/reflectionclass/getfilename.xml b/reference/reflection/reflectionclass/getfilename.xml
index af716f3657..1023d2b009 100644
--- a/reference/reflection/reflectionclass/getfilename.xml
+++ b/reference/reflection/reflectionclass/getfilename.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="reflectionclass.getfilename" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>ReflectionClass::getFileName</refname>
-  <refpurpose>Gets a filename</refpurpose>
+  <refpurpose>Gets the filename of the file in which the class has been defined</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,11 +14,9 @@
    <void />
   </methodsynopsis>
   <para>
-   Gets a filename.
+   Gets the filename of the file in which the class has been defined.
   </para>
 
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -29,7 +27,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   The filename.
+   Returns the filename of the file in which the class has been defined.
+   If the class is defined in the PHP core or in a PHP extension, &false;
+   is returned.
   </para>
  </refsect1>
 
diff --git a/reference/reflection/reflectionclass/newinstance.xml b/reference/reflection/reflectionclass/newinstance.xml
index 877d40b846..ecbff807ab 100644
--- a/reference/reflection/reflectionclass/newinstance.xml
+++ b/reference/reflection/reflectionclass/newinstance.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="reflectionclass.newinstance" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>ReflectionClass::newInstance</refname>
-  <refpurpose>New instance</refpurpose>
+  <refpurpose>Creates a new cass instance from given arguments.</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -15,11 +15,10 @@
    <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
   </methodsynopsis>
   <para>
-   A new instance.
+   Creates a new cass instance of the class, the given arguments are passed
+   to the class constructor.
   </para>
 
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -30,8 +29,8 @@
      <term><parameter>args</parameter></term>
      <listitem>
       <para>
-       Accepts a variable number of arguments which are passed to the function
-       much like <function>call_user_func</function>.
+       Accepts a variable number of arguments which are passed to the class
+       constructor, much like <function>call_user_func</function>.
       </para>
      </listitem>
     </varlistentry>
@@ -42,7 +41,18 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   
+
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   A <classname>ReflectionException</classname> if the class constructor is not public.
+  </para>
+  <para>
+   A <classname>ReflectionException</classname> if the class does not have a constructor
+   and the <parameter>args</parameter> parameter contains one or more parameters.
   </para>
  </refsect1>
 
diff --git a/reference/reflection/reflectionclass/newinstanceargs.xml b/reference/reflection/reflectionclass/newinstanceargs.xml
index e2c13bf1f0..ba58d226e0 100644
--- a/reference/reflection/reflectionclass/newinstanceargs.xml
+++ b/reference/reflection/reflectionclass/newinstanceargs.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="reflectionclass.newinstanceargs" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>ReflectionClass::newInstanceArgs</refname>
-  <refpurpose>New instance args</refpurpose>
+  <refpurpose>Creates a new cass instance from given arguments.</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,7 +14,8 @@
    <methodparam choice="opt"><type>array</type><parameter>args</parameter></methodparam>
   </methodsynopsis>
   <para>
-   New instance args.
+   Creates a new cass instance of the class, the given arguments are passed
+   to the class constructor.
   </para>
 
   &warn.undocumented.func;
@@ -29,7 +30,7 @@
      <term><parameter>args</parameter></term>
      <listitem>
       <para>
-       
+       The parameters to be passed to the class constructor as an <type>array</type>.
       </para>
      </listitem>
     </varlistentry>
@@ -40,7 +41,18 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   
+   Returns a new instance of the class.
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   A <classname>ReflectionException</classname> if the class constructor is not public.
+  </para>
+  <para>
+   A <classname>ReflectionException</classname> if the class does not have a constructor
+   and the <parameter>args</parameter> parameter contains one or more parameters.
   </para>
  </refsect1>
 
diff --git a/reference/reflection/reflectionclass/tostring.xml b/reference/reflection/reflectionclass/tostring.xml
index c61baf21a8..7694c00b82 100644
--- a/reference/reflection/reflectionclass/tostring.xml
+++ b/reference/reflection/reflectionclass/tostring.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="reflectionclass.tostring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>ReflectionClass::__toString</refname>
-  <refpurpose>To string</refpurpose>
+  <refpurpose>Returns the string representation of the ReflectionClass object.</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,11 +14,9 @@
    <void />
   </methodsynopsis>
   <para>
-   To a string.
+   Returns the string representation of the ReflectionClass object.
   </para>
 
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -29,7 +27,88 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   
+   A string representation of this <classname>ReflectionClass</classname> instance.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><methodname>ReflectionClass::__toString</methodname> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$reflectionClass = new ReflectionClass('Exception');
+echo $reflectionClass->__toString();
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+Class [ <internal:Core> class Exception ] {
+
+  - Constants [0] {
+  }
+
+  - Static properties [0] {
+  }
+
+  - Static methods [0] {
+  }
+
+  - Properties [7] {
+    Property [ <default> protected $message ]
+    Property [ <default> private $string ]
+    Property [ <default> protected $code ]
+    Property [ <default> protected $file ]
+    Property [ <default> protected $line ]
+    Property [ <default> private $trace ]
+    Property [ <default> private $previous ]
+  }
+
+  - Methods [10] {
+    Method [ <internal:Core> final private method __clone ] {
+    }
+
+    Method [ <internal:Core, ctor> public method __construct ] {
+
+      - Parameters [3] {
+        Parameter #0 [ <optional> $message ]
+        Parameter #1 [ <optional> $code ]
+        Parameter #2 [ <optional> $previous ]
+      }
+    }
+
+    Method [ <internal:Core> final public method getMessage ] {
+    }
+
+    Method [ <internal:Core> final public method getCode ] {
+    }
+
+    Method [ <internal:Core> final public method getFile ] {
+    }
+
+    Method [ <internal:Core> final public method getLine ] {
+    }
+
+    Method [ <internal:Core> final public method getTrace ] {
+    }
+
+    Method [ <internal:Core> final public method getPrevious ] {
+    }
+
+    Method [ <internal:Core> final public method getTraceAsString ] {
+    }
+
+    Method [ <internal:Core> public method __toString ] {
+    }
+  }
+}
+]]>
+    </screen>
+   </example>
   </para>
  </refsect1>