From 4eefb1e936f416333e05635b0ca2ac10166fdcec Mon Sep 17 00:00:00 2001
From: Adam Harvey <aharvey@php.net>
Date: Sun, 9 Aug 2015 01:15:56 +0000
Subject: [PATCH] Slightly flesh out the Throwable documentation.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@337353 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language/predefined/exception/getcode.xml     |  9 +++++++++
 language/predefined/exception/getfile.xml     |  9 +++++++++
 language/predefined/exception/getline.xml     |  9 +++++++++
 language/predefined/exception/getmessage.xml  |  9 +++++++++
 language/predefined/exception/getprevious.xml |  9 ++++++++-
 language/predefined/exception/gettrace.xml    |  9 +++++++++
 .../predefined/exception/gettraceasstring.xml |  9 +++++++++
 language/predefined/exception/tostring.xml    |  9 +++++++++
 language/predefined/throwable.xml             | 13 ++++++++++--
 language/predefined/throwable/getcode.xml     | 20 +++++++++++++------
 language/predefined/throwable/getfile.xml     | 17 ++++++++++------
 language/predefined/throwable/getline.xml     | 17 ++++++++++------
 language/predefined/throwable/getmessage.xml  | 17 ++++++++++------
 language/predefined/throwable/getprevious.xml | 18 ++++++++++++-----
 language/predefined/throwable/gettrace.xml    | 18 +++++++++++------
 .../predefined/throwable/gettraceasstring.xml | 15 +++++++++-----
 language/predefined/throwable/tostring.xml    | 15 +++++++++-----
 17 files changed, 174 insertions(+), 48 deletions(-)

diff --git a/language/predefined/exception/getcode.xml b/language/predefined/exception/getcode.xml
index 1665c663e7..26988e9441 100644
--- a/language/predefined/exception/getcode.xml
+++ b/language/predefined/exception/getcode.xml
@@ -58,6 +58,15 @@ The exception code is: 30
    </example>
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Throwable::getCode</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
  
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/exception/getfile.xml b/language/predefined/exception/getfile.xml
index c1802c4b69..95abd8233c 100644
--- a/language/predefined/exception/getfile.xml
+++ b/language/predefined/exception/getfile.xml
@@ -55,6 +55,15 @@ try {
    </example>
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Throwable::getFile</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
  
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/exception/getline.xml b/language/predefined/exception/getline.xml
index 5c9f791b11..3d08b7fc60 100644
--- a/language/predefined/exception/getline.xml
+++ b/language/predefined/exception/getline.xml
@@ -55,6 +55,15 @@ The exception was created on line: 3
    </example>
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Throwable::getLine</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
  
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/exception/getmessage.xml b/language/predefined/exception/getmessage.xml
index 92c20c7c5c..14000e552e 100644
--- a/language/predefined/exception/getmessage.xml
+++ b/language/predefined/exception/getmessage.xml
@@ -55,6 +55,15 @@ Some error message
    </example>
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Throwable::getMessage</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
  
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/exception/getprevious.xml b/language/predefined/exception/getprevious.xml
index 83009424be..0170ff98fe 100644
--- a/language/predefined/exception/getprevious.xml
+++ b/language/predefined/exception/getprevious.xml
@@ -74,7 +74,14 @@ try {
   </para>
  </refsect1>
  
-
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Throwable::getPrevious</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
  
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/exception/gettrace.xml b/language/predefined/exception/gettrace.xml
index a3e92ea227..6c9b838df6 100644
--- a/language/predefined/exception/gettrace.xml
+++ b/language/predefined/exception/gettrace.xml
@@ -72,6 +72,15 @@ array(1) {
    </example>
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Throwable::getTrace</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/exception/gettraceasstring.xml b/language/predefined/exception/gettraceasstring.xml
index 33ae3f6a19..65f9c24ab3 100644
--- a/language/predefined/exception/gettraceasstring.xml
+++ b/language/predefined/exception/gettraceasstring.xml
@@ -60,6 +60,15 @@ try {
    </example>
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Throwable::getTraceAsString</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
  
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/exception/tostring.xml b/language/predefined/exception/tostring.xml
index 117b1ddc18..1b91c0b66e 100644
--- a/language/predefined/exception/tostring.xml
+++ b/language/predefined/exception/tostring.xml
@@ -57,6 +57,15 @@ Stack trace:
    </example>
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Throwable::__toString</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
  
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/throwable.xml b/language/predefined/throwable.xml
index dd5a1dbea2..019357bd1d 100644
--- a/language/predefined/throwable.xml
+++ b/language/predefined/throwable.xml
@@ -3,7 +3,7 @@
 
 <phpdoc:classref xml:id="class.throwable" 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 Throwable Interface</title>
+ <title>Throwable</title>
  <titleabbrev>Throwable</titleabbrev>
 
  <partintro>
@@ -12,8 +12,17 @@
   <section xml:id="throwable.intro">
    &reftitle.intro;
    <para>
-    Interface to create an exceptions and errors. Throwable is implemented by Error and Exception class.
+    <classname>Throwable</classname> is the base interface for any object that
+    can be thrown via a &throw; statement, including
+    <classname>Error</classname> and <classname>Exception</classname>.
    </para>
+   <note>
+    <para>
+     PHP classes cannot implement the <classname>Throwable</classname>
+     interface directly, and must instead extend
+     <classname>Exception</classname>.
+    </para>
+   </note>
   </section>
 <!-- }}} -->
 
diff --git a/language/predefined/throwable/getcode.xml b/language/predefined/throwable/getcode.xml
index 2a597c9942..4d085b9f0c 100644
--- a/language/predefined/throwable/getcode.xml
+++ b/language/predefined/throwable/getcode.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="throwable.getcode" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Throwable::getCode</refname>
-  <refpurpose></refpurpose>
+  <refpurpose>Gets the exception code</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,7 +14,7 @@
    <void />
   </methodsynopsis>
   <para>
-   Returns Code
+   Returns the error code associated with the thrown object.
   </para>
  </refsect1>
 
@@ -26,13 +26,21 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
+   Returns the exception code as <type>integer</type> in
+   <classname>Exception</classname> but possibly as other type in
+   <classname>Exception</classname> descendants (for example as
+   <type>string</type> in <classname>PDOException</classname>).
   </para>
  </refsect1>
 
- <refsect1 role="errors"><!-- {{{ -->
-  &reftitle.errors;
- </refsect1><!-- }}} -->
-
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Exception::getCode</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/throwable/getfile.xml b/language/predefined/throwable/getfile.xml
index 67a1d6a046..c27885a6ae 100644
--- a/language/predefined/throwable/getfile.xml
+++ b/language/predefined/throwable/getfile.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="throwable.getfile" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Throwable::getFile</refname>
-  <refpurpose></refpurpose>
+  <refpurpose>Gets the file in which the exception occurred</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,7 +14,7 @@
    <void />
   </methodsynopsis>
   <para>
-   Returns File Name
+   Returns the name of the file from which the object was thrown.
   </para>
  </refsect1>
 
@@ -26,13 +26,18 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
+   Returns the name of the file from which the object was thrown.
   </para>
  </refsect1>
 
- <refsect1 role="errors"><!-- {{{ -->
-  &reftitle.errors;
- </refsect1><!-- }}} -->
-
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Exception::getFile</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/throwable/getline.xml b/language/predefined/throwable/getline.xml
index 774b28295b..271311b0ce 100644
--- a/language/predefined/throwable/getline.xml
+++ b/language/predefined/throwable/getline.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="throwable.getline" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Throwable::getLine</refname>
-  <refpurpose></refpurpose>
+  <refpurpose>Gets the line on which the object was instantiated</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,7 +14,7 @@
    <void />
   </methodsynopsis>
   <para>
-   Returns Line No
+   Returns the line number where the thrown object was instantiated.
   </para>
  </refsect1>
 
@@ -26,13 +26,18 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
+   Returns the line number where the thrown object was instantiated.
   </para>
  </refsect1>
 
- <refsect1 role="errors"><!-- {{{ -->
-  &reftitle.errors;
- </refsect1><!-- }}} -->
-
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Exception::getLine</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/throwable/getmessage.xml b/language/predefined/throwable/getmessage.xml
index 16ca1c43c0..567609a29c 100644
--- a/language/predefined/throwable/getmessage.xml
+++ b/language/predefined/throwable/getmessage.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="throwable.getmessage" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Throwable::getMessage</refname>
-  <refpurpose></refpurpose>
+  <refpurpose>Gets the message</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,7 +14,7 @@
    <void />
   </methodsynopsis>
   <para>
-   Returns message
+   Returns the message associated with the thrown object.
   </para>
  </refsect1>
 
@@ -26,13 +26,18 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
+   Returns the message associated with the thrown object.
   </para>
  </refsect1>
 
- <refsect1 role="errors"><!-- {{{ -->
-  &reftitle.errors;
- </refsect1><!-- }}} -->
-
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Exception::getMessage</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/throwable/getprevious.xml b/language/predefined/throwable/getprevious.xml
index ffabbcaded..2e28519532 100644
--- a/language/predefined/throwable/getprevious.xml
+++ b/language/predefined/throwable/getprevious.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="throwable.getprevious" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Throwable::getPrevious</refname>
-  <refpurpose></refpurpose>
+  <refpurpose>Returns the previous Throwable</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,6 +14,8 @@
    <void />
   </methodsynopsis>
   <para>
+   Returns any previous Throwable (for example, one provided as the third
+   parameter to <methodname>Exception::__construct</methodname>).
   </para>
  </refsect1>
 
@@ -25,13 +27,19 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
+   Returns the previous <classname>Throwable</classname> if available, or
+   &null; otherwise.
   </para>
  </refsect1>
 
- <refsect1 role="errors"><!-- {{{ -->
-  &reftitle.errors;
- </refsect1><!-- }}} -->
-
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Exception::getPrevious</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/throwable/gettrace.xml b/language/predefined/throwable/gettrace.xml
index 859d35cefc..eb2a14a53b 100644
--- a/language/predefined/throwable/gettrace.xml
+++ b/language/predefined/throwable/gettrace.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="throwable.gettrace" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Throwable::getTrace</refname>
-  <refpurpose></refpurpose>
+  <refpurpose>Gets the stack trace</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,7 +14,7 @@
    <void />
   </methodsynopsis>
   <para>
-   Returns Stack Trace
+   Returns the stack trace as an <type>array</type>.
   </para>
  </refsect1>
 
@@ -26,13 +26,19 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
+   Returns the stack trace as an <type>array</type> in the same format as
+   <function>debug_backtrace</function>.
   </para>
  </refsect1>
 
- <refsect1 role="errors"><!-- {{{ -->
-  &reftitle.errors;
- </refsect1><!-- }}} -->
-
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Exception::getTrace</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/throwable/gettraceasstring.xml b/language/predefined/throwable/gettraceasstring.xml
index 0d84159b2b..d661907e0c 100644
--- a/language/predefined/throwable/gettraceasstring.xml
+++ b/language/predefined/throwable/gettraceasstring.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="throwable.gettraceasstring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Throwable::getTraceAsString</refname>
-  <refpurpose></refpurpose>
+  <refpurpose>Gets the stack trace as a string</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -25,13 +25,18 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
+   Returns the stack trace as a string.
   </para>
  </refsect1>
 
- <refsect1 role="errors"><!-- {{{ -->
-  &reftitle.errors;
- </refsect1><!-- }}} -->
-
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Exception::getTraceAsString</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/language/predefined/throwable/tostring.xml b/language/predefined/throwable/tostring.xml
index 903e5dfb26..3b14c2fb9b 100644
--- a/language/predefined/throwable/tostring.xml
+++ b/language/predefined/throwable/tostring.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="throwable.tostring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Throwable::__toString</refname>
-  <refpurpose></refpurpose>
+  <refpurpose>Gets a string representation of the thrown object</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -25,13 +25,18 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
+   Returns the <type>string</type> representation of the thrown object.
   </para>
  </refsect1>
 
- <refsect1 role="errors"><!-- {{{ -->
-  &reftitle.errors;
- </refsect1><!-- }}} -->
-
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Exception::__toString</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file