Documentation for Core nearly all in place.

lib/Recess/Core/Callable.php

@@ -2,7 +2,7 @@
 namespace Recess\Core; /** @addtogroup Core *//** @{ */
 
 /**
- * Turns any PHP value which is_callable() into an invocable object/closure with call() and apply() methods. 
+ * Turns an is_callable() PHP value into a directly invocable object/closure with call() and apply() methods. 
  * 
  * Note: Callable does not support passing arguments by-reference.
  * 

lib/Recess/Core/Event.php

@@ -18,10 +18,11 @@
 class Event implements ICallable {
 /** @} */
 
+	/** Listeners registered to receive notice of the event trigger. */
 	protected $callbacks = array();
 
 	/**
-	 * Call each callback with arguments passed to __invoke 
+	 * Trigger the event and call each callback with arguments passed to __invoke. 
 	 */
 	function __invoke() {
 		if(!empty($this->callbacks)) {

lib/Recess/Core/Hash.php

@@ -3,15 +3,18 @@
 /** @addtogroup Core *//** @{ */
 
 /**
- * An object-oriented PHP array with functional methods like map(),each(),filter(). 
+ * An object-oriented PHP array with higher-order methods like map(), each(), & filter(). 
  * Hash implements IHash (which extends ArrayAccess) so it can be used as an array.
- * IHash also implies higher order methods: 
+ * IHash also requires higher-order methods: 
  * 	- map()
  * 	- reduce()
  *	- each()
  *	- filter()
  * 
- * @include examples/Recess/Core/Wrappable.php
+ * @include examples/Recess/Core/Hash.php
+ * 
+ * To run this example code from the command line:
+ * @code php lib/Recess/examples/Recess/Core/Hash.php @endcode
  * 
  * @author Kris Jordan <http://krisjordan.com>
  * @copyright RecessFramework.org 2008-2010

lib/Recess/Core/ICallable.php

@@ -1,8 +1,8 @@
 <?php
-namespace Recess\Core;
+namespace Recess\Core; /** @addtogroup Core *//** @{ */
 
 interface ICallable {
-	
+/** @} */
 	/**
 	 * Magic method that invokes the is_callable() value the instance was constructed with.
 	 * 

lib/Recess/Core/functions.php

@@ -2,41 +2,99 @@
 namespace Recess\Core;
 /** @addtogroup Core *//** @{ */
 
-function map($array, $mapFn) {
-	$results = array();
+/**
+ * Invoke a callable one-by-one over an array of values.
+ * 
+ * @code
+ * each(array(1,2,3), function($x) { echo $x+$x," "; });
+ * //> 2 4 6
+ * @endcode
+ * 
+ * @param $array array of mixed values
+ * @param $callable is_callable
+ */
+function each($array, $callable) {
 	foreach($array as $value) {
-		$results[] = $mapFn($value);
+		$callable($value);
+	}
+}
+
+/**
+ * Invoke a callable one-by-one $array's values, if result is
+ * true the value is included in the returned array, if not true 
+ * it is filtered out.
+ * 
+ * @code
+ * var_export(
+ * 	filter(array(1,2,3,4), function($x) { return $x % 2 === 0; })
+ * );
+ * //> array(2,4)
+ * @endcode
+ * 
+ * @param $array array of mixed values
+ * @param $callable is_callable
+ * @return array
+ */
+function filter($array, $callable) {
+	$results = array();
+	foreach($array as $key => $value) {
+		if($callable($value) === true) {
+			$results[$key] = $value;
+		}
+	}
+	return $results;
+}
+
+/**
+ * Invoke a callable one-by-one over an array of values and return an array
+ * containing the result of each invocation.
+ * 
+ * @code
+ * var_export(
+ * 	map(array(1,2,3,4), function($x) { return $x * $x; })
+ * );
+ * //> array(1,4,9,16)
+ * @endcode
+ * 
+ * @param $array array of mixed values
+ * @param $callable is_callable
+ * @return array
+ */
+function map($array, $callable) {
+	$results = array();
+	foreach($array as $key => $value) {
+		$results[$key] = $callable($value);
 	}
 	return $results;
 }
 
-function reduce($array, $combineFn, $identity) {
+/**
+ * Reduce an array of values using a callable that combines the array's
+ * values. If the array contains 0 or 1 elements the identity value 
+ * will be returned.
+ * 
+ * @code
+ * var_export(
+ * 	reduce(array(1,2,3,4), function($x,$y) { return $x + $y; }, 1)
+ * );
+ * //> 10
+ * @endcode
+ * 
+ * @param $array array of mixed values
+ * @param $callable is_callable
+ * @param $identity mixed return value if $array contains 0 or 1 elements
+ * @return array
+ */
+function reduce($array, $callable, $identity) {
 	if(count($array) <= 1) {
 		$out = $identity;
 	} else if(count($array) > 1) {
 		$out = array_shift($array);
 		do {
 			$next = array_shift($array);
-			$out = $combineFn($out, $next);
+			$out = $callable($out, $next);
 		} while(!empty($array));
 	}
 	return $out;
 }
-
-function each($array, $fn) {
-	foreach($array as $value) {
-		$fn($value);
-	}
-	return $array;
-}
-
-function filter($array, $filterFn) {
-	$results = array();
-	foreach($array as $key => $value) {
-		if($filterFn($value) === true) {
-			$results[$key] = $value;
-		}
-	}
-	return $results;
-}
 /**@}*/

lib/Recess/examples/Recess/Core/Callable.php

@@ -28,7 +28,11 @@ static function baz() { echo "baz\n"; }
 //> baz
 
 // ==== Closures
-$callable = new Callable(function($value = 'Closure') { print("$value!\n"); });
+$callable = new Callable(
+	function($value = 'Closure') { 
+		print("$value!\n"); 
+	}
+);
 $callable();
 //> Closure!
 

lib/Recess/examples/Recess/Core/Hash.php

@@ -1,14 +1,22 @@
 <?php include "lib/Recess/Recess.php"; use Recess\Core\Hash;
 
+// ==== Use a Hash like PHP's built-in array
 $hash = new Hash(array('key' => 'value'));
-echo $hash['key']; // output: value
+$hash[] = 'foo';
+$hash['bar'] = 'baz';
+echo $hash['key'],"\n"; 
+//> value
 
+// ==== Construct Hash with values
 $hash = new Hash(1,2,3,4);
-print_r($hash->map(function($x) { return $x*$x; }));
-// array (1,4,9,16);
+echo "$hash[0] $hash[1] $hash[2] $hash[3]\n";
+//> 1 2 3 4
 
-$hash = new Hash(1,2,3);
-foreach($hash as $element) {
-  echo "$element,";
-}
-// 1,2,3,
+// ==== Use higher-order methods
+$hash->map(function($x) { return $x*$x; })
+     ->filter(function($x) { return $x % 2 === 0; })
+     ->each(function($x) { echo "$x "; });
+//> 4 16
+$sum = $hash->reduce(function($x,$y) { return $x + $y; }, 1);
+echo "\nSum: $sum\n";
+//> Sum: 10