comments

src/TUnit/framework/mock/InvocationExpectation.php

@@ -1,50 +1,164 @@
 <?php
 
+	/**
+	 * InvocationExpectation
+	 *
+	 * @package TUnit
+	 * @author  Tommy Montgomery
+	 * @version 1.0
+	 * @since   1.0
+	 */
+
+	/**
+	 * Represents what is expected of a mock object's method
+	 * invocation
+	 *
+	 * @package TUnit
+	 * @author  Tommy Montgomery
+	 * @version 1.0
+	 * @since   1.0
+	 */
 	class InvocationExpectation {
 		
-		protected $className;
+		/**
+		 * The method of the mock invocation
+		 *
+		 * @var string
+		 */
 		protected $method;
+		
+		/**
+		 * The number of times the method is expected to be invoked
+		 *
+		 * @var int
+		 */
 		protected $count;
+		
+		/**
+		 * The arguments the method should be invoked with
+		 *
+		 * @var array
+		 */
 		protected $args;
+		
+		/**
+		 * The value to return after invocation
+		 *
+		 * @var mixed
+		 */
 		protected $returnValue;
+		
+		/**
+		 * String to echo after invocation
+		 *
+		 * @var mixed
+		 */
 		protected $echoString;
+		
+		/**
+		 * Whether the expectation has been verified
+		 *
+		 * @var bool
+		 */
 		protected $verified;
 		
+		/**
+		 * Constructor
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  sttring $methodName
+		 */
 		public function __construct($methodName) {
-			$this->method       = $methodName;
+			$this->method      = $methodName;
-			$this->count        = 0;
+			$this->count       = 0;
-			$this->args         = array();
+			$this->args        = array();
-			$this->returnValue  = null;
+			$this->returnValue = null;
-			$this->echoString   = null;
+			$this->echoString  = null;
-			$this->verified     = false;
+			$this->verified    = false;
 		}
 		
+		/**
+		 * Gets the method name
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @return string
+		 */
 		public final function getMethod() {
 			return $this->method;
 		}
 		
+		/**
+		 * Gets the count
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @return int
+		 */
 		public final function getCount() {
 			return $this->count;
 		}
 		
+		/**
+		 * Gets the expected arguments
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @return array
+		 */
 		public final function getArgs() {
 			return $this->args;
 		}
 		
+		/**
+		 * The number of times you expect the method to be called
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  int $count
+		 * @return InvocationExpectation
+		 */
 		public function toBeCalled($count) {
 			$this->count = $count;
 			return $this;
 		}
 		
-		public function toBeCallExactly($count) {
+		/**
-			throw new BadMethodCallException('Not implemented yet');
+		 * The arguments you expect the method to be called with
-		}
+		 *
-		
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @return InvocationExpectation
+		 */
 		public function withArguments() {
 			$this->args = func_get_args();
 			return $this;
 		}
 		
+		/**
+		 * The string you want the method to echo
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  mixed $value Primitive or __toString()-able object
+		 * @throws InvalidArgumentException
+		 * @return InvocationExpectation
+		 */
 		public function toEcho($value) {
 			if (!is_scalar($value)) {
 				if (is_object($value)) {
@@ -63,18 +177,57 @@
 			return $this;
 		}
 		
+		/**
+		 * The string you want the method to echo
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    toEcho()
+		 * 
+		 * @param  mixed $value
+		 * @return InvocationExpectation
+		 */
 		public function andToEcho($value) {
 			return $this->toEcho($value);
 		}
 		
+		/**
+		 * The value you want the method to return
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  mixed $value
+		 */
 		public function toReturn($value) {
 			$this->returnValue = $value;
 		}
 		
+		/**
+		 * The value you want the method to return
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    toReturn()
+		 * 
+		 * @param  mixed $value
+		 */
 		public function andToReturn($value) {
 			$this->toReturn($value);
 		}
 		
+		/**
+		 * Executes the invocation expectation
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @return mixed The return value given by {@link toReturn()}
+		 */
 		public function execute() {
 			if (!empty($this->echoString)) {
 				echo $this->echoString;
@@ -83,10 +236,34 @@
 			return $this->returnValue;
 		}
 		
+		/**
+		 * Determines whether this expectation matches the given invocation
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    MockInvocation::getMethod()
+		 * @uses    MockInvocation::getCount()
+		 * @uses    MockInvocation::getArgs()
+		 * @uses    countIsAcceptable()
+		 * 
+		 * @param  MockInvocation $invocation
+		 * @return bool
+		 */
 		public function matchesInvocation(MockInvocation $invocation) {
 			return $this->method === $invocation->getMethod() && $this->countIsAcceptable($invocation->getCount()) && $this->args == $invocation->getArgs();
 		}
 		
+		/**
+		 * Determines if the given count is acceptable to this expectation
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  int $count
+		 * @return bool
+		 */
 		protected function countIsAcceptable($count) {
 			switch ($this->count) {
 				case TestCase::ANY:
@@ -98,10 +275,28 @@
 			}
 		}
 		
+		/**
+		 * Gets whether this expectation has been verified
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @return bool
+		 */
 		public final function isVerified() {
 			return $this->verified;
 		}
 		
+		/**
+		 * Sets whether this expectation has been verified
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  bool $verified
+		 */
 		public final function setVerified($verified) {
 			$this->verified = (bool)$verified;
 		}

src/TUnit/framework/mock/InvocationTracker.php

@@ -1,13 +1,54 @@
 <?php
 
+	/**
+	 * InvocationTracker
+	 *
+	 * @package TUnit
+	 * @author  Tommy Montgomery
+	 * @version 1.0
+	 * @since   1.0
+	 */
+
+	/**
+	 * Tracks mock invocations
+	 *
+	 * @package TUnit
+	 * @author  Tommy Montgomery
+	 * @version 1.0
+	 * @since   1.0
+	 */
 	class InvocationTracker {
 		
+		/**
+		 * @var array
+		 */
 		protected $invocations;
 		
+		/**
+		 * Constructor
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 */
 		public function __construct() {
 			$this->invocations = array();
 		}
 		
+		/**
+		 * Registers a invocation
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    MockRegistry::getExpectations()
+		 * @uses    MockInvocation::getClass()
+		 * @uses    InvocationExpectation::matchsInvocation()
+		 * @uses    InvocationExpectation::setVerified()
+		 * 
+		 * @param  MockInvocation $invocation
+		 * @return InvocationExpectation|bool Returns the matching InvocationExpectation if there is one, or false if not
+		 */
 		public function registerInvocation(MockInvocation $invocation) {
 			$this->invocations[] = $invocation;
 			
@@ -21,10 +62,30 @@
 			return false;
 		}
 		
-		public function getInvocations() {
+		/**
+		 * Gets
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @return mixed
+		 */
+		public final function getInvocations() {
 			return $this->invocations;
 		}
 		
+		/**
+		 * Verifies all invocations
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    MockRegistry::getAllExpectations()
+		 * @uses    InvocationExpectation::isVerified()
+		 * 
+		 * @return bool true if all invocation expectations have been verified, false if not
+		 */
 		public function verify() {
 			foreach (MockRegistry::getAllExpectations() as $expectation) {
 				if (!$expectation->isVerified()) {

src/TUnit/framework/mock/MockHandler.php

@@ -1,13 +1,54 @@
 <?php
 
+	/**
+	 * MockHandler
+	 *
+	 * @package TUnit
+	 * @author  Tommy Montgomery
+	 * @version 1.0
+	 * @since   1.0
+	 */
+
+	/**
+	 * Simple wrapper for mock objects so we don't pollute
+	 * objects with member variables
+	 *
+	 * @package TUnit
+	 * @author  Tommy Montgomery
+	 * @version 1.0
+	 * @since   1.0
+	 */
 	final class MockHandler {
 		
+		/**
+		 * @var string
+		 */
 		private $className;
 		
+		/**
+		 * Constructor
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  object $mock The mock object
+		 */
 		public function __construct($mock) {
 			$this->className = get_class($mock);
 		}
 		
+		/**
+		 * The method the mock object expects to call
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    MockRegistry::addExpectation()
+		 * 
+		 * @param  string $methodName The method that is expected to be invoked
+		 * @return InvocationExpectation
+		 */
 		public function expectsMethod($methodName) {
 			$expectation = new InvocationExpectation($methodName);
 			MockRegistry::addExpectation($this->className, $expectation);