more doc blocks.

cake/libs/controller/controller.php

@@ -27,15 +27,28 @@
 App::import('View', 'View', false);
 
 /**
- * Controller
- *
  * Application controller class for organization of business logic.
  * Provides basic functionality, such as rendering views inside layouts,
  * automatic model availability, redirection, callbacks, and more.
  *
- * @package       cake
- * @subpackage    cake.cake.libs.controller
- * @link          http://book.cakephp.org/view/956/Introduction
+ * Controllers should provide a number of 'action' methods.  These are public methods on the controller
+ * that are not prefixed with a '_' and not part of Controller.  Each action serves as an endpoint for 
+ * performing a specific action on a resource or collection of resources.  For example adding or editing a new
+ * object, or listing a set of objects.
+ *
+ * You can access request parameters, using `$this->request`.  The request object contains all the POST, GET and FILES
+ * that were part of the request. 
+ *
+ * After performing the required actions, controllers are responsible for creating a response.  This usually
+ * takes the form of a generated View, or possibly a redirection to another controller action.  In either case
+ * `$this->response` allows you to manipulate all aspects of the response.
+ *
+ * Controllers are created by Dispatcher based on request parameters and routing. By default controllers and actions
+ * use conventional names.  For example `/posts/index` maps to `PostsController::index()`.  You can re-map urls
+ * using Router::connect().
+ *
+ * @package    cake.libs.controller
+ * @link       http://book.cakephp.org/view/956/Introduction
  */
 class Controller extends Object {
 
@@ -148,7 +161,7 @@ class Controller extends Object {
 	public $autoLayout = true;
 
 /**
- * Instance of Component used to handle callbacks.
+ * Instance of ComponentCollection used to handle callbacks.
  *
  * @var string
  */
@@ -240,7 +253,8 @@ class Controller extends Object {
 	public $scaffold = false;
 
 /**
- * Holds current methods of the controller
+ * Holds current methods of the controller.  This is a list of all the methods reachable
+ * via url.  Modifying this array, will allow you to change which methods can be reached.
  *
  * @var array
  */
@@ -550,7 +564,7 @@ public function shutdownProcess() {
  *
  * @return mixed Associative array of the HTTP codes as keys, and the message
  *    strings as values, or null of the given $code does not exist.
- * @deprecated
+ * @deprecated Use CakeResponse::httpCodes();
  */
 	public function httpCodes($code = null) {
 		return $this->response->httpCodes($code);
@@ -671,7 +685,7 @@ public function redirect($url, $status = null, $exit = true) {
  *
  * @param string $status The header message that is being set.
  * @return void
- * @deprecated
+ * @deprecated Use CakeResponse::header()
  */
 	public function header($status) {
 		$this->response->header($status);
@@ -859,7 +873,7 @@ public function referer($default = null, $local = false) {
  *
  * @return void
  * @link http://book.cakephp.org/view/988/disableCache
- * @deprecated
+ * @deprecated Use CakeResponse::disableCache()
  */
 	public function disableCache() {
 		$this->response->disableCache();
@@ -960,15 +974,17 @@ public function paginate($object = null, $scope = array(), $whitelist = array())
 	}
 
 /**
- * Called before the controller action.
+ * Called before the controller action.  You can use this method to configure and customize components
+ * or perform logic that needs to happen before each controller action.
  *
  * @link http://book.cakephp.org/view/984/Callbacks
  */
 	public function beforeFilter() {
 	}
 
 /**
- * Called after the controller action is run, but before the view is rendered.
+ * Called after the controller action is run, but before the view is rendered. You can use this method
+ * to perform logic or set view variables that are required on every request.
  *
  * @link http://book.cakephp.org/view/984/Callbacks
  */

cake/libs/router.php

@@ -22,10 +22,23 @@
 App::import('Core', 'route/CakeRoute');
 
 /**
- * Parses the request URL into controller, action, and parameters.
+ * Parses the request URL into controller, action, and parameters.  Uses the connected routes
+ * to match the incoming url string to parameters that will allow the request to be dispatched.  Also
+ * handles converting parameter lists into url strings, using the connected routes.  Routing allows you to decouple
+ * the way the world interacts with your application (urls) and the implementation (controllers and actions).
  *
- * @package       cake
- * @subpackage    cake.cake.libs
+ * ### Connecting routes
+ *
+ * Connecting routes is done using Router::connect().  When parsing incoming requests or reverse matching
+ * parameters, routes are enumerated in the order they were connected.  You can modify the order of connected
+ * routes using Router::promote().  For more information on routes and how to connect them see Router::connect().
+ *
+ * ### Named parameters
+ *
+ * Named parameters allow you to embed key:value pairs into path segments.  This allows you create hash
+ * structures using urls.  You can define how named parameters work in your application using Router::connectNamed()
+ *
+ * @package       cake.libs
  */
 class Router {
 
@@ -276,6 +289,7 @@ public static function connect($route, $defaults = array(), $options = array())
  * Redirects /posts/* to http://google.com with a HTTP status of 302
  *
  * ### Options:
+ *
  * - `status` Sets the HTTP status (default 301)
  * - `persist` Passes the params to the redirected route, if it can
  *