Merge branch 'master' into rfc/escaper

src/Address.php

@@ -26,17 +26,18 @@
  * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  */
-class Address implements AddressDescription
+class Address implements Address\AddressInterface
 {
     protected $email;
     protected $name;
 
     /**
      * Constructor
-     * 
-     * @param  string $email 
-     * @param  null|string $name 
-     * @return void
+     *
+     * @param  string $email
+     * @param  null|string $name
+     * @throws Exception\InvalidArgumentException
+     * @return Address
      */
     public function __construct($email, $name = null)
     {
@@ -64,7 +65,7 @@ public function getEmail()
     /**
      * Retrieve name
      * 
-     * @return null|string
+     * @return string
      */
     public function getName()
     {

src/AddressDescription.php → src/Address/AddressInterface.php

@@ -14,19 +14,21 @@
  *
  * @category   Zend
  * @package    Zend_Mail
+ * @subpackage Address
  * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  */
 
-namespace Zend\Mail;
+namespace Zend\Mail\Address;
 
 /**
  * @category   Zend
  * @package    Zend_Mail
+ * @subpackage Address
  * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  */
-interface AddressDescription
+interface AddressInterface
 {
     public function getEmail();
     public function getName();

src/AddressList.php

@@ -20,8 +20,8 @@
 
 namespace Zend\Mail;
 
-use Countable,
-    Iterator;
+use Countable;
+use Iterator;
 
 /**
  * @category   Zend
@@ -40,17 +40,17 @@ class AddressList implements Countable, Iterator
 
     /**
      * Add an address to the list
-     * 
-     * @param  string|AddressDescription $emailOrAddress 
-     * @param  null|string $name 
+     *
+     * @param  string|Address\AddressInterface $emailOrAddress
+     * @param  null|string $name
+     * @throws Exception\InvalidArgumentException
      * @return AddressList
      */
     public function add($emailOrAddress, $name = null)
     {
         if (is_string($emailOrAddress)) {
             $emailOrAddress = $this->createAddress($emailOrAddress, $name);
-        }
-        if (!$emailOrAddress instanceof AddressDescription) {
+        } elseif (!$emailOrAddress instanceof Address\AddressInterface) {
             throw new Exception\InvalidArgumentException(sprintf(
                 '%s expects an email address or %s\Address object as its first argument; received "%s"',
                 __METHOD__,
@@ -71,11 +71,12 @@ public function add($emailOrAddress, $name = null)
     /**
      * Add many addresses at once
      *
-     * If an email key is provided, it will be used as the email, and the value 
-     * as the name. Otherwise, the value is passed as the sole argument to add(), 
-     * and, as such, can be either email strings or AddressDescription objects.
-     * 
-     * @param  array $addresses 
+     * If an email key is provided, it will be used as the email, and the value
+     * as the name. Otherwise, the value is passed as the sole argument to add(),
+     * and, as such, can be either email strings or Address\AddressInterface objects.
+     *
+     * @param  array $addresses
+     * @throws Exception\RuntimeException
      * @return AddressList
      */
     public function addMany(array $addresses)
@@ -125,7 +126,7 @@ public function has($email)
      * Get an address by email
      * 
      * @param  string $email 
-     * @return false|AddressDescription
+     * @return boolean|Address\AddressInterface
      */
     public function get($email)
     {
@@ -166,8 +167,10 @@ public function count()
 
     /**
      * Rewind iterator
-     * 
-     * @return void
+     *
+     * @return mixed the value of the first addresses element, or false if the addresses is
+     * empty.
+     * @see addresses
      */
     public function rewind()
     {
@@ -196,8 +199,10 @@ public function key()
 
     /**
      * Move to next item
-     * 
-     * @return void
+     *
+     * @return mixed the addresses value in the next place that's pointed to by the
+     * internal array pointer, or false if there are no more elements.
+     * @see addresses
      */
     public function next()
     {

src/Exception/BadMethodCallException.php

@@ -0,0 +1,34 @@
+<?php
+/**
+ * Zend Framework
+ *
+ * LICENSE
+ *
+ * This source file is subject to the new BSD license that is bundled
+ * with this package in the file LICENSE.txt.
+ * It is also available through the world-wide-web at this URL:
+ * http://framework.zend.com/license/new-bsd
+ * If you did not receive a copy of the license and are unable to
+ * obtain it through the world-wide-web, please send an email
+ * to license@zend.com so we can send you a copy immediately.
+ *
+ * @category   Zend
+ * @package    Zend_Mail
+ * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ */
+
+namespace Zend\Mail\Exception;
+
+/**
+ * Exception for Zend_Mail component.
+ *
+ * @category   Zend
+ * @package    Zend_Mail
+ * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ */
+class BadMethodCallException extends \BadMethodCallException implements 
+    ExceptionInterface
+{
+}

src/Exception/DomainException.php

@@ -0,0 +1,38 @@
+<?php
+/**
+ * Zend Framework
+ *
+ * LICENSE
+ *
+ * This source file is subject to the new BSD license that is bundled
+ * with this package in the file LICENSE.txt.
+ * It is also available through the world-wide-web at this URL:
+ * http://framework.zend.com/license/new-bsd
+ * If you did not receive a copy of the license and are unable to
+ * obtain it through the world-wide-web, please send an email
+ * to license@zend.com so we can send you a copy immediately.
+ *
+ * @category   Zend
+ * @package    Zend_Mail
+ * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
+ * @version    $Id$
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ */
+
+namespace Zend\Mail\Exception;
+
+use Zend\Mail\Exception;
+
+/**
+ * Exception for Zend_Mail component.
+ *
+ * @category   Zend
+ * @package    Zend_Mail
+ * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ */
+class DomainException
+    extends \DomainException
+    implements ExceptionInterface
+{
+}

src/Exception.php → src/Exception/ExceptionInterface.php

@@ -18,17 +18,14 @@
  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  */
 
-/**
- * @namespace
- */
-namespace Zend\Mail;
+namespace Zend\Mail\Exception;
 
 /**
  * @category   Zend
  * @package    Zend_Mail
  * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  */
-interface Exception
+interface ExceptionInterface
 {
 }

src/Exception/InvalidArgumentException.php

@@ -18,11 +18,7 @@
  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  */
 
-/**
- * @namespace
- */
 namespace Zend\Mail\Exception;
-use Zend\Mail\Exception;
 
 /**
  * Exception for Zend_Mail component.
@@ -34,6 +30,6 @@
  */
 class InvalidArgumentException
     extends \InvalidArgumentException
-    implements Exception
+    implements ExceptionInterface
 {
 }

src/Exception/OutOfBoundsException.php

@@ -20,8 +20,6 @@
 
 namespace Zend\Mail\Exception;
 
-use Zend\Mail\Exception;
-
 /**
  * Exception for Zend_Mail component.
  *
@@ -32,6 +30,6 @@
  */
 class OutOfBoundsException
     extends \OutOfBoundsException
-    implements Exception
+    implements ExceptionInterface
 {
 }

src/Exception/RuntimeException.php

@@ -20,8 +20,6 @@
 
 namespace Zend\Mail\Exception;
 
-use Zend\Mail\Exception;
-
 /**
  * Exception for Zend_Mail component.
  *
@@ -32,6 +30,6 @@
  */
 class RuntimeException
     extends \RuntimeException
-    implements Exception
+    implements ExceptionInterface
 {
 }