From 04f28335808d671224cb2110b35cbc1105aefccc Mon Sep 17 00:00:00 2001
From: Hannes Magnusson <bjori@php.net>
Date: Wed, 2 Feb 2011 14:11:16 +0000
Subject: [PATCH] - Replace "void" with &no.function.params; - Replace some
 "returns true if all was good" with &return.success; - Document exceptions
 thrown - Document the ctor array keys properly - Minor update to some
 examples

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@307957 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/amqp/amqpconnection/connect.xml     | 13 ++--
 reference/amqp/amqpconnection/construct.xml   | 68 +++++++++++++++++--
 reference/amqp/amqpconnection/isconnected.xml | 11 ++-
 reference/amqp/amqpconnection/reconnect.xml   | 13 ++--
 reference/amqp/amqpconnection/sethost.xml     | 10 ++-
 reference/amqp/amqpconnection/setlogin.xml    | 10 ++-
 reference/amqp/amqpconnection/setpassword.xml | 10 ++-
 reference/amqp/amqpconnection/setport.xml     | 10 ++-
 8 files changed, 117 insertions(+), 28 deletions(-)

diff --git a/reference/amqp/amqpconnection/connect.xml b/reference/amqp/amqpconnection/connect.xml
index f8006118f0..9c70458a30 100644
--- a/reference/amqp/amqpconnection/connect.xml
+++ b/reference/amqp/amqpconnection/connect.xml
@@ -20,15 +20,13 @@
 
  <refsect1 role="parameters">
   &reftitle.parameters;
-  <para>
-      void
-  </para>
+  &no.function.parameters;
  </refsect1>
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-      Returns true if connection was successful, false otherwise.
+   &return.success;
   </para>
  </refsect1>
 
@@ -48,8 +46,11 @@ $cnn = new AMQPConnection();
 $cnn->setLogin('mylogin');
 $cnn->setPassword('mypass');
 
-if (!$cnn->connect()) {
- throw new Exception('Could not connect');
+if ($cnn->connect()) {
+    echo "Established a connection to the broker";
+}
+else {
+    echo "Cannot connect to the broker";
 }
 
 
diff --git a/reference/amqp/amqpconnection/construct.xml b/reference/amqp/amqpconnection/construct.xml
index e8ea7a5aa2..ebc9eb40c4 100644
--- a/reference/amqp/amqpconnection/construct.xml
+++ b/reference/amqp/amqpconnection/construct.xml
@@ -27,12 +27,49 @@
      <listitem>
       <para>
        The <parameter>credentials</parameter> is an optional array of credential information for connecting to the AMQP
-       broker. The keys used in the <parameter>credentials</parameter> array are: host, port, vhost, login and password.
-       All other keys will be ignored.
+       broker.
        </para>
-      <para>
-       For each missing credential, the extension will check the ini settings or use the default value.
-      </para>
+      <table>
+       <title>Supported indexes</title>
+       <tgroup cols="3">
+        <thead>
+         <row>
+          <entry>key</entry>
+          <entry>Description</entry>
+          <entry>Default value</entry>
+         </row>
+        </thead>
+        <tbody>
+         <row>
+          <!-- FIXME: WTF? Seriously? 32char max? -->
+          <entry><emphasis>host</emphasis></entry>
+          <entry>The host to connect too <note><simpara>Max 32 characters</simpara></note></entry>
+          <entry><link linkend="ini.amqp.host">amqp.host</link></entry>
+         </row>
+         <row>
+          <entry><emphasis>port</emphasis></entry>
+          <entry>Port on the host</entry>
+          <entry><link linkend="ini.amqp.port">amqp.port</link></entry>
+         </row>
+         <row>
+          <entry><emphasis>vhost</emphasis></entry>
+          <entry>The virtual host on the host <note><simpara>Max 32 characters</simpara></note></entry>
+          <entry><link linkend="ini.amqp.vhost">amqp.vhost</link></entry>
+         </row>
+         <row>
+          <entry><emphasis>login</emphasis></entry>
+          <entry>The login name to use. <note><simpara>Max 32 characters</simpara></note></entry>
+          <entry><link linkend="ini.amqp.login">amqp.login</link></entry>
+         </row>
+         <row>
+          <entry><emphasis>password</emphasis></entry>
+          <entry>Password <note><simpara>Max 32 characters</simpara></note></entry>
+          <entry><link linkend="ini.amqp.password">amqp.password</link></entry>
+         </row>
+        </tbody>
+       </tgroup>
+      </table>
+      <para>All other keys will be ignored.</para>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -46,6 +83,14 @@
   </para>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws <classname>AMQPException</classname> exception on parameter parsing
+   failures, and option errors.
+  </para>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
@@ -55,9 +100,10 @@
 <![CDATA[
 <?php
 
-/* Create a connection using all default credentials: */
+/* Create a connection using the INI values */
 $connection1 = new AMQPConnection();
 
+/* Specifying all keys */
 $connection2 = new AMQPConnection(array(
     'host' => 'example.host',
     'vhost' => '/',
@@ -73,7 +119,15 @@ $connection2 = new AMQPConnection(array(
   </para>
  </refsect1>
 
-
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <note>
+   <para>
+    A connection will not be established untill
+    <methodname>AMQPConnection::connect</methodname> is called.
+   </para>
+  </note>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/amqp/amqpconnection/isconnected.xml b/reference/amqp/amqpconnection/isconnected.xml
index 3ddceb9ca7..2d1cf58b86 100644
--- a/reference/amqp/amqpconnection/isconnected.xml
+++ b/reference/amqp/amqpconnection/isconnected.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="amqpconnection.isconnected" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>AMQPConnection::isConnected</refname>
-  <refpurpose>Determine if the AMQPConnection object is still connected to the broker.</refpurpose>
+  <refpurpose>Determine if the AMQPConnection object is connected to the broker.</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -42,10 +42,14 @@
 
 /* Create a new connection */
 $cnn = new AMQPConnection();
+$conn->connect();
 
 /* Check that connection is working */
-if (!$cnn->isConnected()) {
-    die('The connection to the server was not established.');
+if ($cnn->isConnected()) {
+    echo "Connected to the broker \o/";
+}
+else {
+    echo "Cannot connect to the broker";
 }
 
 ?>
@@ -78,3 +82,4 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->
+
diff --git a/reference/amqp/amqpconnection/reconnect.xml b/reference/amqp/amqpconnection/reconnect.xml
index 2759d3eac7..8a88d4f6b0 100644
--- a/reference/amqp/amqpconnection/reconnect.xml
+++ b/reference/amqp/amqpconnection/reconnect.xml
@@ -20,15 +20,13 @@
 
  <refsect1 role="parameters">
   &reftitle.parameters;
-  <para>
-      void
-  </para>
+  &no.function.parameters;
  </refsect1>
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-      Returns true if reconnect was successful, false otherwise.
+   &return.success;
   </para>
  </refsect1>
 
@@ -48,15 +46,14 @@ $cnn = new AMQPConnection();
 $cnn->setLogin('mylogin');
 $cnn->setPassword('mypass');
 
-if (!$cnn->connect()) {
- throw new Exception('Could not connect');
-}
+$cnn->connect();
 
 // do something interesting
 
+
 // ensure we have a valid connection
 if (!$cnn->reconnect()) {
- throw new Exception('Could not reconnect');
+    echo "Could not reconnect to server";
 }
 
 ?>
diff --git a/reference/amqp/amqpconnection/sethost.xml b/reference/amqp/amqpconnection/sethost.xml
index 13f342b59e..3d7fbccec7 100644
--- a/reference/amqp/amqpconnection/sethost.xml
+++ b/reference/amqp/amqpconnection/sethost.xml
@@ -37,7 +37,15 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-      void
+   &return.success;
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws an <classname>AMQPConnectionException</classname> if
+   <parameter>host</parameter> is longer then 1024characters.
   </para>
  </refsect1>
 
diff --git a/reference/amqp/amqpconnection/setlogin.xml b/reference/amqp/amqpconnection/setlogin.xml
index 11aabb83d3..44aca75af4 100644
--- a/reference/amqp/amqpconnection/setlogin.xml
+++ b/reference/amqp/amqpconnection/setlogin.xml
@@ -37,7 +37,15 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-      void
+   &return.success;
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws an <classname>AMQPConnectionException</classname> if
+   <parameter>login</parameter> is longer then 32characters.
   </para>
  </refsect1>
 
diff --git a/reference/amqp/amqpconnection/setpassword.xml b/reference/amqp/amqpconnection/setpassword.xml
index 3c71eddda2..9fa1dd72f6 100644
--- a/reference/amqp/amqpconnection/setpassword.xml
+++ b/reference/amqp/amqpconnection/setpassword.xml
@@ -37,7 +37,15 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-      void
+   &return.success;
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws an <classname>AMQPConnectionException</classname> if
+   <parameter>password</parameter> is longer then 32characters.
   </para>
  </refsect1>
 
diff --git a/reference/amqp/amqpconnection/setport.xml b/reference/amqp/amqpconnection/setport.xml
index 94b2a08ded..afe3348266 100644
--- a/reference/amqp/amqpconnection/setport.xml
+++ b/reference/amqp/amqpconnection/setport.xml
@@ -37,7 +37,15 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-      void
+   &return.success;
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws an <classname>AMQPConnectionException</classname> if
+   <parameter>port</parameter> is longer not between 1 and 65535.
   </para>
  </refsect1>