From a917da5674a4c81bd1fa6ca0c2762442ce7eabf6 Mon Sep 17 00:00:00 2001
From: Joris van de Sande <joris@php.net>
Date: Thu, 22 Jul 2010 20:03:49 +0000
Subject: [PATCH] - Added parameter and return value documentation for
 ReflectionMethod constructor - Updated documentation and added examples for
 the following ReflectionMethod methods: export, getDeclaringClass,
 getPrototype, invoke, invokeArgs, isDestructor, __toString

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@301478 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../reflection/reflectionmethod/construct.xml | 21 ++++---
 .../reflection/reflectionmethod/export.xml    |  3 +-
 .../reflectionmethod/getdeclaringclass.xml    | 44 ++++++++++++--
 .../reflectionmethod/getmodifiers.xml         | 60 +++++++++++++++++--
 .../reflectionmethod/getprototype.xml         | 53 ++++++++++++++--
 .../reflection/reflectionmethod/invoke.xml    | 33 +++++++++-
 .../reflectionmethod/invokeargs.xml           | 33 +++++++++-
 .../reflectionmethod/isdestructor.xml         |  4 +-
 .../reflection/reflectionmethod/tostring.xml  | 47 +++++++++++++--
 9 files changed, 259 insertions(+), 39 deletions(-)

diff --git a/reference/reflection/reflectionmethod/construct.xml b/reference/reflection/reflectionmethod/construct.xml
index 14765da637..28bfb912ac 100644
--- a/reference/reflection/reflectionmethod/construct.xml
+++ b/reference/reflection/reflectionmethod/construct.xml
@@ -11,15 +11,13 @@
   &reftitle.description;
   <methodsynopsis>
    <methodname>ReflectionMethod::__construct</methodname>
-   <methodparam><type>string</type><parameter>class_or_method</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>name</parameter></methodparam>
+   <methodparam><type>mixed</type><parameter>class</parameter></methodparam>
+   <methodparam><type>string</type><parameter>name</parameter></methodparam>
   </methodsynopsis>
   <para>
    Constructs a new <classname>ReflectionMethod</classname>.
   </para>
 
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -27,10 +25,10 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>class_or_method</parameter></term>
+     <term><parameter>class</parameter></term>
      <listitem>
       <para>
-       
+       Classname or object (instance of the class) that contains the method.
       </para>
      </listitem>
     </varlistentry>
@@ -38,7 +36,7 @@
      <term><parameter>name</parameter></term>
      <listitem>
       <para>
-       
+       Name of the method.
       </para>
      </listitem>
     </varlistentry>
@@ -49,7 +47,14 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   
+   &return.void;
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   A <classname>ReflectionException</classname> if the the given method does not exist.
   </para>
  </refsect1>
 
diff --git a/reference/reflection/reflectionmethod/export.xml b/reference/reflection/reflectionmethod/export.xml
index 29de88563b..c35e2caffd 100644
--- a/reference/reflection/reflectionmethod/export.xml
+++ b/reference/reflection/reflectionmethod/export.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="reflectionmethod.export" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>ReflectionMethod::export</refname>
-  <refpurpose>Export</refpurpose>
+  <refpurpose>Export a reflection method.</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -67,6 +67,7 @@
   <para>
    <simplelist>
     <member><methodname>ReflectionMethod::__construct</methodname></member>
+    <member><methodname>ReflectionMethod::__toString</methodname></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/reflection/reflectionmethod/getdeclaringclass.xml b/reference/reflection/reflectionmethod/getdeclaringclass.xml
index a1cb857a8e..f767ce019d 100644
--- a/reference/reflection/reflectionmethod/getdeclaringclass.xml
+++ b/reference/reflection/reflectionmethod/getdeclaringclass.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="reflectionmethod.getdeclaringclass" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>ReflectionMethod::getDeclaringClass</refname>
-  <refpurpose>Gets declaring class</refpurpose>
+  <refpurpose>Gets declaring class for the reflected method.</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,11 +14,8 @@
    <void />
   </methodsynopsis>
   <para>
-   Gets the declaring class.
+   Gets the declaring class for the reflected method.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -29,7 +26,42 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   A <classname>ReflectionClass</classname>.
+   A <classname>ReflectionClass</classname> object of the class that the
+   reflected method is part of.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><methodname>ReflectionFunction::getDeclaringClass</methodname> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+class HelloWorld {
+
+    protected function sayHelloTo($name) {
+        return 'Hello ' . $name;
+    }
+
+}
+
+$reflectionMethod = new ReflectionMethod(new HelloWorld(), 'sayHelloTo');
+var_dump($reflectionMethod->getDeclaringClass());
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+object(ReflectionClass)#2 (1) {
+  ["name"]=>
+  string(10) "HelloWorld"
+}
+]]>
+    </screen>
+   </example>
   </para>
  </refsect1>
 
diff --git a/reference/reflection/reflectionmethod/getmodifiers.xml b/reference/reflection/reflectionmethod/getmodifiers.xml
index df1e449088..d80cbf5b4c 100644
--- a/reference/reflection/reflectionmethod/getmodifiers.xml
+++ b/reference/reflection/reflectionmethod/getmodifiers.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="reflectionmethod.getmodifiers" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>ReflectionMethod::getModifiers</refname>
-  <refpurpose>Gets modifiers</refpurpose>
+  <refpurpose>Gets the method modifiers</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,11 +14,8 @@
    <void />
   </methodsynopsis>
   <para>
-   Gets the modifiers.
+   Gets the method modifiers.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -29,7 +26,58 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   A numeric representation of the modifiers.
+   A numeric representation of the modifiers. The modifiers are listed below.
+   The actual meanings of these modifiers are described in the
+   <link linkend="reflectionmethod.constants">predefined constants</link>.
+       <table>
+        <title>ReflectionMethod modifiers</title>
+        <tgroup cols="2">
+         <thead>
+          <row>
+           <entry>value</entry>
+           <entry>constant</entry>
+          </row>
+         </thead>
+         <tbody>
+          <row>
+           <entry>1</entry>
+           <entry>
+            <link linkend="reflectionmethod.constants.is-static">ReflectionMethod::IS_STATIC</link>
+           </entry>
+          </row>
+          <row>
+           <entry>2</entry>
+           <entry>
+            <link linkend="reflectionmethod.constants.is-abstract">ReflectionMethod::IS_ABSTRACT</link>
+           </entry>
+          </row>
+          <row>
+           <entry>4</entry>
+           <entry>
+            <link linkend="reflectionmethod.constants.is-final">ReflectionMethod::IS_FINAL</link>
+           </entry>
+          </row>
+          <row>
+           <entry>256</entry>
+           <entry>
+            <link linkend="reflectionmethod.constants.is-public">ReflectionMethod::IS_PUBLIC</link>
+           </entry>
+          </row>
+          <row>
+           <entry>512</entry>
+           <entry>
+            <link linkend="reflectionmethod.constants.is-protected">ReflectionMethod::IS_PROTECTED</link>
+           </entry>
+          </row>
+          <row>
+           <entry>1024</entry>
+           <entry>
+            <link linkend="reflectionmethod.constants.is-private">ReflectionMethod::IS_PRIVATE</link>
+           </entry>
+          </row>
+         </tbody>
+        </tgroup>
+       </table>
   </para>
  </refsect1>
 
diff --git a/reference/reflection/reflectionmethod/getprototype.xml b/reference/reflection/reflectionmethod/getprototype.xml
index 62bd7639af..59f6b3e5c9 100644
--- a/reference/reflection/reflectionmethod/getprototype.xml
+++ b/reference/reflection/reflectionmethod/getprototype.xml
@@ -4,21 +4,19 @@
 <refentry xml:id="reflectionmethod.getprototype" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>ReflectionMethod::getPrototype</refname>
-  <refpurpose>Gets prototype</refpurpose>
+  <refpurpose>Gets the method prototype (if there is one).</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>ReflectionMethod::getPrototype</methodname>
+   <modifier>public</modifier> <type>ReflectionMethod</type><methodname>ReflectionMethod::getPrototype</methodname>
    <void />
   </methodsynopsis>
   <para>
-   Gets the methods prototype.
+   Returns the methods prototype.
   </para>
 
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -29,7 +27,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   The prototype.
+   A <classname>ReflectionMethod</classname> instance of the method prototype.
   </para>
  </refsect1>
 
@@ -41,6 +39,49 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><methodname>ReflectionMethod::getPrototype</methodname> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+class Hello {
+
+    public function sayHelloTo($name) {
+        return 'Hello ' . $name;
+    }
+
+}
+class HelloWorld extends Hello {
+
+    public function sayHelloTo($name) {
+        return 'Hello world: ' . $name;
+    }
+
+}
+
+$reflectionMethod = new ReflectionMethod('HelloWorld', 'sayHelloTo');
+var_dump($reflectionMethod->getPrototype());
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+object(ReflectionMethod)#2 (2) {
+  ["name"]=>
+  string(10) "sayHelloTo"
+  ["class"]=>
+  string(5) "Hello"
+}
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
diff --git a/reference/reflection/reflectionmethod/invoke.xml b/reference/reflection/reflectionmethod/invoke.xml
index efd63a32c3..27ed87f1d7 100644
--- a/reference/reflection/reflectionmethod/invoke.xml
+++ b/reference/reflection/reflectionmethod/invoke.xml
@@ -19,8 +19,6 @@
    Invokes a reflected method.
   </para>
 
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -67,6 +65,37 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><methodname>ReflectionFunction::invoke</methodname> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+class HelloWorld {
+
+    public function sayHelloTo($name) {
+        return 'Hello ' . $name;
+    }
+
+}
+
+$reflectionMethod = new ReflectionMethod('HelloWorld', 'sayHelloTo');
+echo $reflectionMethod->invoke(new HelloWorld(), 'Mike');
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+Hello Mike
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
diff --git a/reference/reflection/reflectionmethod/invokeargs.xml b/reference/reflection/reflectionmethod/invokeargs.xml
index afcb3557b9..d71ecc1930 100644
--- a/reference/reflection/reflectionmethod/invokeargs.xml
+++ b/reference/reflection/reflectionmethod/invokeargs.xml
@@ -18,8 +18,6 @@
    Invoke arguments.
   </para>
 
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -65,6 +63,37 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><methodname>ReflectionFunction::invokeArgs</methodname> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+class HelloWorld {
+
+    public function sayHelloTo($name) {
+        return 'Hello ' . $name;
+    }
+
+}
+
+$reflectionMethod = new ReflectionMethod('HelloWorld', 'sayHelloTo');
+echo $reflectionMethod->invokeArgs(new HelloWorld(), array('Mike'));
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+Hello Mike
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
diff --git a/reference/reflection/reflectionmethod/isdestructor.xml b/reference/reflection/reflectionmethod/isdestructor.xml
index 6f5bb15b39..9899ea7aa3 100644
--- a/reference/reflection/reflectionmethod/isdestructor.xml
+++ b/reference/reflection/reflectionmethod/isdestructor.xml
@@ -14,7 +14,7 @@
    <void />
   </methodsynopsis>
   <para>
-   Checks if the method is a destructor. 
+   Checks if the method is a destructor.
   </para>
  </refsect1>
 
@@ -26,7 +26,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   &true; if the method is a destructor, otherwise false;
+   &true; if the method is a destructor, otherwise &false;
   </para>
  </refsect1>
 
diff --git a/reference/reflection/reflectionmethod/tostring.xml b/reference/reflection/reflectionmethod/tostring.xml
index e25bf8f47f..1043403dbd 100644
--- a/reference/reflection/reflectionmethod/tostring.xml
+++ b/reference/reflection/reflectionmethod/tostring.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="reflectionmethod.tostring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>ReflectionMethod::__toString</refname>
-  <refpurpose>To string</refpurpose>
+  <refpurpose>Returns the string representation of the Reflection method object.</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,11 +14,8 @@
    <void />
   </methodsynopsis>
   <para>
-   To string.
+   Returns the string representation of the Reflection method object.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -29,7 +26,45 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   
+   A string representation of this <classname>ReflectionMethod</classname> instance.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><methodname>ReflectionFunction::__toString</methodname> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+class HelloWorld {
+
+    public function sayHelloTo($name) {
+        return 'Hello ' . $name;
+    }
+
+}
+
+$reflectionMethod = new ReflectionMethod(new HelloWorld(), 'sayHelloTo');
+echo $reflectionMethod;
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+Method [ <user> public method sayHelloTo ] {
+  @@ /var/www/examples/reflection.php 16 - 18
+
+  - Parameters [1] {
+    Parameter #0 [ <required> $name ]
+  }
+}
+
+]]>
+    </screen>
+   </example>
   </para>
  </refsect1>