Added more API documentation and standard formatting in Console, Exte…

…nsions and Matcher

src/PHPSpec/Console/Command.php

@@ -110,6 +110,16 @@ public function setAutotest(\PHPSpec\Extensions\Autotest $autotest)
         $this->_autotest = $autotest;
     }
 
+    /**
+     * Returns the options
+     * 
+     * @return \PHPSpec\Console\Getopt
+     */ 
+    public function getOptions()
+    {
+        return $this->_options;
+    }
+
     /**
      * Creates a runner if none given (inline factory)
      * 

src/PHPSpec/Describe/Functions.php

@@ -15,7 +15,8 @@
  * @category   PHPSpec
  * @package    PHPSpec
  * @copyright  Copyright (c) 2007-2009 Pádraic Brady, Travis Swicegood
- * @copyright  Copyright (c) 2010-2011 Pádraic Brady, Travis Swicegood, Marcello Duarte
+ * @copyright  Copyright (c) 2010-2011 Pádraic Brady, Travis Swicegood,
+ *                                     Marcello Duarte
  * @license    http://www.gnu.org/licenses/lgpl-3.0.txt GNU Lesser General Public Licence Version 3
  */
 
@@ -27,7 +28,9 @@
 function describe()
 {
     $args = func_get_args();
-    return call_user_func_array(array("\\PHPSpec\\Specification",'getSpec'), $args);
+    return call_user_func_array(
+        array("\\PHPSpec\\Specification",'getSpec'), $args
+    );
 }
 
 /**
@@ -50,7 +53,9 @@ function PHPSpec_ErrorHandler($errno, $errstr, $errfile, $errline)
     array_shift($backtrace);
 
     include_once 'PHPSpec/Runner/ErrorException.php';
-    throw new \PHPSpec\Runner\ErrorException($errstr, $errno, $errfile, $errline, $backtrace);
+    throw new \PHPSpec\Runner\ErrorException(
+        $errstr, $errno, $errfile, $errline, $backtrace
+    );
 
     return true;
 }

src/PHPSpec/Extensions/Autotest.php

@@ -1,34 +1,63 @@
 <?php
-
+/**
+ * PHPSpec
+ *
+ * LICENSE
+ *
+ * This file is subject to the GNU Lesser General Public License Version 3
+ * that is bundled with this package in the file LICENSE.
+ * It is also available through the world-wide-web at this URL:
+ * http://www.gnu.org/licenses/lgpl-3.0.txt
+ * 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@phpspec.org so we can send you a copy immediately.
+ *
+ * @category   PHPSpec
+ * @package    PHPSpec
+ * @copyright  Copyright (c) 2007-2009 Pádraic Brady, Travis Swicegood
+ * @copyright  Copyright (c) 2010-2011 Pádraic Brady, Travis Swicegood,
+ *                                     Marcello Duarte
+ * @license    http://www.gnu.org/licenses/lgpl-3.0.txt GNU Lesser General Public Licence Version 3
+ */
 namespace PHPSpec\Extensions;
 
+/**
+ * @category   PHPSpec
+ * @package    PHPSpec
+ * @copyright  Copyright (c) 2007-2009 Pádraic Brady, Travis Swicegood
+ * @copyright  Copyright (c) 2010-2011 Pádraic Brady, Travis Swicegood,
+ *                                     Marcello Duarte
+ * @license    http://www.gnu.org/licenses/lgpl-3.0.txt GNU Lesser General Public Licence Version 3
+ */
 class Autotest
 {
-	/**
-     * The autotest() static method serves as PHPSpec's Autotester. It will
+    /**
+     * @FIXME! Replace this with Autorun.php
+     * 
+     * The autotest method serves as PHPSpec's Autotester. It will
      * run all tests continually, with 10 second delays between each
      * iterative run and report as normal for each iteration to the console
      * output.
      * 
      * Use the CTRL+C key combination to trigger an exit from the console
      * running loop used for Autotesting.
      *
-     * @param \PHPSpec\Console\Getopt $options
+     * @param \PHPSpec\Console\Command $options
      */   
-	public function run(\PHPSpec\Console\Command $command)
-	{
-		set_time_limit(0);
+    public function run(\PHPSpec\Console\Command $command)
+    {
+        set_time_limit(0);
 
-    	if (isset($command->options->a)) {
-    		$command->options->a = null;
-    	}
-        if (isset($command->options->autotest)) {
-            $command->options->autotest = null;
+        if (isset($command->getOptions()->a)) {
+            $command->getOptions()->a = null;
+        }
+        if (isset($command->getOptions()->autotest)) {
+            $command->getOptions()->autotest = null;
         }
 
-    	while(true) {
-    	    $command->run($options);
-    	    sleep(10);
-    	}
-	}
+        while (true) {
+            $command->run($command->getOptions());
+            sleep(10);
+        }
+    }
 }

src/PHPSpec/Matcher/Be.php

@@ -10,37 +10,65 @@
  * http://www.gnu.org/licenses/lgpl-3.0.txt
  * 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@phpspec.org so we can send you a copy immediately.
+ * to license@phpspec.net so we can send you a copy immediately.
  *
- * @category   PHPSpec
- * @package    PHPSpec
- * @copyright  Copyright (c) 2007 P�draic Brady, Travis Swicegood
- * @license    http://www.gnu.org/licenses/lgpl-3.0.txt GNU Lesser General Public Licence Version 3
+ * @category  PHPSpec
+ * @package   PHPSpec
+ * @copyright Copyright (c) 2007-2009 Pádraic Brady, Travis Swicegood
+ * @copyright Copyright (c) 2010-2011 Pádraic Brady, Travis Swicegood,
+ *                                    Marcello Duarte
+ * @license   http://www.gnu.org/licenses/lgpl-3.0.txt GNU Lesser General Public Licence Version 3
  */
 namespace PHPSpec\Matcher;
 
+/**
+ * @see \PHPSpec\Matcher
+ */
 use \PHPSpec\Matcher;
+
+/**
+ * @see \PHPSpec\Matcher\Equal
+ */
 use \PHPSpec\Matcher\Equal;
 
 /**
  * @category   PHPSpec
  * @package    PHPSpec
- * @copyright  Copyright (c) 2007 P�draic Brady, Travis Swicegood
+ * @copyright  Copyright (c) 2007-2009 Pádraic Brady, Travis Swicegood
+ * @copyright  Copyright (c) 2010-2011 Pádraic Brady, Travis Swicegood,
+ *                                     Marcello Duarte
  * @license    http://www.gnu.org/licenses/lgpl-3.0.txt GNU Lesser General Public Licence Version 3
  */
 class Be extends Equal implements Matcher
 {
 
+    /**
+     * Returns failure message in case we are using should
+     * 
+     * @return string
+     */
     public function getFailureMessage()
     {
-        return 'expected ' . var_export($this->_expected, true) . ', got ' . var_export($this->_actual, true) . ' (using be())';
+        return 'expected ' . var_export($this->_expected, true) .
+               ', got ' . var_export($this->_actual, true) . ' (using be())';
     }
 
+    /**
+     * Returns failure message in case we are using should not
+     * 
+     * @return string
+     */
     public function getNegativeFailureMessage()
     {
-        return 'expected ' . var_export($this->_actual, true) . ' not to be ' . var_export($this->_expected, true) . ' (using be())';
+        return 'expected ' . var_export($this->_actual, true) . ' not to be ' .
+               var_export($this->_expected, true) . ' (using be())';
     }
 
+    /**
+     * Returns the matcher description
+     * 
+     * @return string
+     */
     public function getDescription()
     {
         return 'be ' . var_export($this->_expected, true);

src/PHPSpec/Matcher/BeAnInstanceOf.php

@@ -10,34 +10,63 @@
  * http://www.gnu.org/licenses/lgpl-3.0.txt
  * 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@phpspec.org so we can send you a copy immediately.
+ * to license@phpspec.net so we can send you a copy immediately.
  *
- * @category   PHPSpec
- * @package    PHPSpec
- * @copyright  Copyright (c) 2007 Pádraic Brady, Travis Swicegood
- * @license    http://www.gnu.org/licenses/lgpl-3.0.txt GNU Lesser General Public Licence Version 3
+ * @category  PHPSpec
+ * @package   PHPSpec
+ * @copyright Copyright (c) 2007-2009 Pádraic Brady, Travis Swicegood
+ * @copyright Copyright (c) 2010-2011 Pádraic Brady, Travis Swicegood,
+ *                                    Marcello Duarte
+ * @license   http://www.gnu.org/licenses/lgpl-3.0.txt GNU Lesser General Public Licence Version 3
  */
 namespace PHPSpec\Matcher;
 
+/**
+ * @see \PHPSpec\Matcher
+ */
 use \PHPSpec\Matcher;
+
 /**
  * @category   PHPSpec
  * @package    PHPSpec
- * @copyright  Copyright (c) 2007 Pádraic Brady, Travis Swicegood
+ * @copyright  Copyright (c) 2007-2009 Pádraic Brady, Travis Swicegood
+ * @copyright  Copyright (c) 2010-2011 Pádraic Brady, Travis Swicegood,
+ *                                     Marcello Duarte
  * @license    http://www.gnu.org/licenses/lgpl-3.0.txt GNU Lesser General Public Licence Version 3
  */
 class BeAnInstanceOf implements Matcher
 {
 
+    /**
+     * The expected value
+     * 
+     * @var mixed
+     */
     protected $_expected = null;
 
+    /**
+     * The actual value
+     * 
+     * @var object
+     */
     protected $_actual = null;
 
+    /**
+     * Matcher is usually constructed with the expected value
+     * 
+     * @param string $expected
+     */
     public function __construct($expected)
     {
         $this->_expected = $expected;
     }
 
+    /**
+     * Checks whether actual value is an instance of expected
+     * 
+     * @param mixed $expected
+     * @return boolean
+     */
     public function matches($actual)
     {
         if ($actual instanceof $this->_expected) {
@@ -55,16 +84,33 @@ public function matches($actual)
         return false;
     }
 
+    /**
+     * Returns failure message in case we are using should
+     * 
+     * @return string
+     */
     public function getFailureMessage()
     {
-        return 'expected ' . var_export($this->_expected, true) . ', got ' . var_export($this->_actual, true) . ' (using beAnInstanceOf())';
+        return 'expected ' . var_export($this->_expected, true) . ', got ' .
+               var_export($this->_actual, true) . ' (using beAnInstanceOf())';
     }
 
+    /**
+     * Returns failure message in case we are using should not
+     * 
+     * @return string
+     */
     public function getNegativeFailureMessage()
     {
-        return 'expected ' . var_export($this->_actual, true) . ' not to be ' . var_export($this->_expected, true) . ' (using beAnInstanceOf())';
+        return 'expected ' . var_export($this->_actual, true) . ' not to be ' .
+               var_export($this->_expected, true) . ' (using beAnInstanceOf())';
     }
 
+    /**
+     * Returns the matcher description
+     * 
+     * @return string
+     */
     public function getDescription()
     {
         return 'be an instance of ' . var_export($this->_expected, true);