Merge pull request #366 from shama/patch-docs

Add/move docblocks to make text available in the API docs

lib/Cake/Cache/Engine/FileEngine.php

@@ -21,7 +21,11 @@
  */
 
 /**
- * File Storage engine for cache
+ * File Storage engine for cache.  Filestorage is the slowest cache storage
+ * to read and write.  However, it is good for servers that don't have other storage
+ * engine available, or have content which is not performance sensitive.
+ *
+ * You can configure a FileEngine cache, using Cache::config()
  *
  * @package       Cake.Cache.Engine
  */

lib/Cake/Console/Command/ApiShell.php

@@ -24,6 +24,8 @@ App::uses('File', 'Utility');
 /**
  * API shell to show method signatures of CakePHP core classes.
  *
+ * Implementation of a Cake Shell to show CakePHP core method signatures.
+ *
  * @package       Cake.Console.Command
  */
 class ApiShell extends AppShell {

lib/Cake/Console/Command/BakeShell.php

@@ -24,7 +24,11 @@ App::uses('AppShell', 'Console/Command');
 App::uses('Model', 'Model');
 
 /**
- * Bake is a command-line code generation utility for automating programmer chores.
+ * Command-line code generation utility to automate programmer chores.
+ *
+ * Bake is CakePHP's code generation script, which can help you kickstart
+ * application development by writing fully functional skeleton controllers,
+ * models, and views. Going further, Bake can also write Unit Tests for you.
  *
  * @package       Cake.Console.Command
  * @link          http://book.cakephp.org/2.0/en/console-and-shells/code-generation-with-bake.html

lib/Cake/Console/Command/SchemaShell.php

@@ -27,6 +27,9 @@ App::uses('CakeSchema', 'Model');
 /**
  * Schema is a command-line database management utility for automating programmer chores.
  *
+ * Schema is CakePHP's database management utility. This helps you maintain versions of
+ * of your database.
+ *
  * @package       Cake.Console.Command
  * @link          http://book.cakephp.org/2.0/en/console-and-shells/schema-management-and-migrations.html
  */

lib/Cake/Console/Command/Task/PluginTask.php

@@ -21,7 +21,7 @@ App::uses('File', 'Utility');
 App::uses('Folder', 'Utility');
 
 /**
- * Task class for creating a plugin
+ * The Plugin Task handles creating an empty plugin, ready to be used
  *
  * @package       Cake.Console.Command.Task
  */

lib/Cake/Controller/CakeErrorController.php

@@ -18,6 +18,14 @@
  * @since         CakePHP(tm) v 2.0
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
+/**
+ * Error Handling Controller
+ *
+ * Controller used by ErrorHandler to render error views.
+ *
+ * @package       Cake.Controller
+ */
 class CakeErrorController extends AppController {
 
 /**

lib/Cake/Controller/Component/RequestHandlerComponent.php

@@ -22,7 +22,11 @@
 App::uses('Xml', 'Utility');
 
 /**
- * Request object for handling HTTP requests
+ * Request object for handling alternative HTTP requests
+ *
+ * Alternative HTTP requests can come from wireless units like mobile phones, palmtop computers,
+ * and the like. These units have no use for Ajax requests, and this Component can tell how Cake
+ * should respond to the different needs of a handheld computer and a desktop machine.
  *
  * @package       Cake.Controller.Component
  * @link http://book.cakephp.org/2.0/en/core-libraries/components/request-handling.html

lib/Cake/Controller/Component/SecurityComponent.php

@@ -22,7 +22,14 @@ App::uses('String', 'Utility');
 App::uses('Security', 'Utility');
 
 /**
- * SecurityComponent
+ * The Security Component creates an easy way to integrate tighter security in 
+ * your application. It provides methods for various tasks like:
+ *
+ * - Restricting which HTTP methods your application accepts.
+ * - CSRF protection.
+ * - Form tampering protection
+ * - Requiring that SSL be used.
+ * - Limiting cross controller communication.
  *
  * @package       Cake.Controller.Component
  * @link http://book.cakephp.org/2.0/en/core-libraries/components/security-component.html

lib/Cake/Controller/Component/SessionComponent.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * SessionComponent.  Provides access to Sessions from the Controller layer
+ * SessionComponent. Provides access to Sessions from the Controller layer
  *
  * PHP 5
  *
@@ -21,9 +21,9 @@ App::uses('Component', 'Controller');
 App::uses('CakeSession', 'Model/Datasource');
 
 /**
- * Session Component.
+ * The CakePHP SessionComponent provides a way to persist client data between 
- *
+ * page requests. It acts as a wrapper for the `$_SESSION` as well as providing 
- * Session handling from the controller.
+ * convenience methods for several `$_SESSION` related functions.
  *
  * @package       Cake.Controller.Component
  * @link http://book.cakephp.org/2.0/en/core-libraries/components/sessions.html

lib/Cake/Controller/ComponentCollection.php

@@ -19,6 +19,12 @@
 App::uses('ObjectCollection', 'Utility');
 App::uses('Component', 'Controller');
 
+/**
+ * Components collection is used as a registry for loaded components and handles loading
+ * and constructing component class objects.
+ *
+ * @package       Cake.Controller
+ */
 class ComponentCollection extends ObjectCollection {
 
 /**

lib/Cake/Core/CakePlugin.php

@@ -18,7 +18,8 @@
  */
 
 /**
- * CakePlugin class
+ * CakePlugin is responsible for loading and unloading plugins. It also can 
+ * retrieve plugin paths and load their bootstrap and routes files.
  *
  * @package       Cake.Core
  * @link http://book.cakephp.org/2.0/en/plugins.html

lib/Cake/Model/AclNode.php

@@ -16,15 +16,11 @@
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 
-/**
- * Load Model and AppModel
- */
 App::uses('AppModel', 'Model');
 
 /**
  * ACL Node
  *
- *
  * @package       Cake.Model
  */
 class AclNode extends AppModel {

lib/Cake/Model/Aco.php

@@ -16,9 +16,6 @@
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 
-/**
- * Load Model and AppModel
- */
 App::uses('AppModel', 'Model');
 
 /**

lib/Cake/Model/AcoAction.php

@@ -16,9 +16,6 @@
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 
-/**
- * Load Model and AppModel
- */
 App::uses('AppModel', 'Model');
 
 /**

lib/Cake/Model/Aro.php

@@ -16,9 +16,6 @@
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 
-/**
- * Load Model and AppModel
- */
 App::uses('AppModel', 'Model');
 
 /**

lib/Cake/Model/Behavior/AclBehavior.php

@@ -23,6 +23,8 @@ App::uses('AclNode', 'Model');
 /**
  * ACL behavior
  *
+ * Enables objects to easily tie into an ACL system
+ *
  * @package       Cake.Model.Behavior
  * @link http://book.cakephp.org/2.0/en/core-libraries/behaviors/acl.html
  */

lib/Cake/Model/Behavior/ContainableBehavior.php

@@ -20,8 +20,9 @@
  */
 
 /**
- * Behavior to allow for dynamic and atomic manipulation of a Model's associations used for a find call. Most useful for limiting
+ * Behavior to allow for dynamic and atomic manipulation of a Model's associations 
- * the amount of associations and data returned.
+ * used for a find call. Most useful for limiting the amount of associations and 
+ * data returned.
  *
  * @package       Cake.Model.Behavior
  * @link http://book.cakephp.org/2.0/en/core-libraries/behaviors/containable.html

lib/Cake/Model/CakeSchema.php

@@ -16,6 +16,7 @@
  * @since         CakePHP(tm) v 1.2.0.5550
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('Model', 'Model');
 App::uses('AppModel', 'Model');
 App::uses('ConnectionManager', 'Model');

lib/Cake/Model/ConnectionManager.php

@@ -24,6 +24,9 @@ App::uses('DataSource', 'Model/Datasource');
 /**
  * Manages loaded instances of DataSource objects
  *
+ * Provides an interface for loading and enumerating connections defined in 
+ * app/Config/database.php
+ *
  * @package       Cake.Model
  */
 class ConnectionManager {

lib/Cake/Model/Datasource/Database/Postgres.php

@@ -22,8 +22,6 @@ App::uses('DboSource', 'Model/Datasource');
 /**
  * PostgreSQL layer for DBO.
  *
- * Long description for class
- *
  * @package       Cake.Model.Datasource.Database
  */
 class Postgres extends DboSource {

lib/Cake/Model/Model.php

@@ -19,9 +19,6 @@
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 
-/**
- * Included libs
- */
 App::uses('ClassRegistry', 'Utility');
 App::uses('Validation', 'Utility');
 App::uses('String', 'Utility');

lib/Cake/Model/Permission.php

@@ -16,9 +16,6 @@
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 
-/**
- * Load Model and AppModel
- */
 App::uses('AppModel', 'Model');
 
 /**

lib/Cake/Network/CakeSocket.php

@@ -16,6 +16,7 @@
  * @since         CakePHP(tm) v 1.2.0
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('Validation', 'Utility');
 
 /**

lib/Cake/Network/Email/AbstractTransport.php

@@ -18,7 +18,7 @@
  */
 
 /**
- * Abstract class
+ * Abstract transport for sending email
  *
  * @package       Cake.Network.Email
  */

lib/Cake/Network/Email/CakeEmail.php

@@ -16,6 +16,7 @@
  * @since         CakePHP(tm) v 2.0.0
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('Validation', 'Utility');
 App::uses('Multibyte', 'I18n');
 App::uses('AbstractTransport', 'Network/Email');

lib/Cake/Network/Email/MailTransport.php

@@ -18,7 +18,7 @@
  */
 
 /**
- * Mail class
+ * Send mail using mail() function
  *
  * @package       Cake.Network.Email
  */

lib/Cake/Network/Email/SmtpTransport.php

@@ -16,10 +16,11 @@
  * @since         CakePHP(tm) v 2.0.0
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('CakeSocket', 'Network');
 
 /**
- * SendEmail class
+ * Send mail using SMTP protocol
  *
  * @package       Cake.Network.Email
  */

lib/Cake/Network/Http/HttpResponse.php

@@ -18,7 +18,7 @@
  */
 
 /**
- * HTTP Response
+ * HTTP Response from HttpSocket.
  *
  * @package       Cake.Network.Http
  */

lib/Cake/Routing/Dispatcher.php

@@ -20,9 +20,6 @@
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 
-/**
- * List of helpers to include
- */
 App::uses('Router', 'Routing');
 App::uses('CakeRequest', 'Network');
 App::uses('CakeResponse', 'Network');

lib/Cake/Routing/Route/CakeRoute.php

@@ -11,6 +11,7 @@
  * @since         CakePHP(tm) v 1.3
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('Set', 'Utility');
 
 /**

lib/Cake/Routing/Route/PluginShortRoute.php

@@ -11,6 +11,7 @@
  * @since         CakePHP(tm) v 1.3
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('CakeRoute', 'Routing/Route');
 
 /**

lib/Cake/Routing/Route/RedirectRoute.php

@@ -12,6 +12,7 @@
  * @since         CakePHP(tm) v 2.0
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('CakeResponse', 'Network');
 App::uses('CakeRoute', 'Routing/Route');
 

lib/Cake/TestSuite/CakeTestLoader.php

@@ -18,6 +18,14 @@
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  * @package Cake.TestSuite
  */
+
+/**
+ * TestLoader for CakePHP Test suite.
+ *
+ * Turns partial paths used on the testsuite console and web UI into full file paths.
+ *
+ * @package Cake.TestSuite
+ */
 class CakeTestLoader extends PHPUnit_Runner_StandardTestSuiteLoader {
 
 /**

lib/Cake/TestSuite/CakeTestSuite.php

@@ -16,8 +16,14 @@
  * @since         CakePHP(tm) v 2.0
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('Folder', 'Utility');
 
+/**
+ * A class to contain test cases and run them with shared fixtures
+ *
+ * @package       Cake.TestSuite
+ */
 class CakeTestSuite extends PHPUnit_Framework_TestSuite {
 
 /**

lib/Cake/TestSuite/Coverage/BaseCoverageReport.php

@@ -17,6 +17,13 @@
  * @since         CakePHP(tm) v 2.0
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
+/**
+ * Abstract class for common CoverageReport methods.
+ * Provides several template methods for custom output.
+ *
+ * @package       Cake.TestSuite.Coverage
+ */
 abstract class BaseCoverageReport {
 
 /**

lib/Cake/TestSuite/Coverage/HtmlCoverageReport.php

@@ -16,8 +16,14 @@
  * @since         CakePHP(tm) v 2.0
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('BaseCoverageReport', 'TestSuite/Coverage');
 
+/**
+ * Generates code coverage reports in HTML from data obtained from PHPUnit
+ *
+ * @package       Cake.TestSuite.Coverage
+ */
 class HtmlCoverageReport extends BaseCoverageReport {
 
 /**

lib/Cake/TestSuite/Coverage/TextCoverageReport.php

@@ -16,8 +16,14 @@
  * @since         CakePHP(tm) v 2.0
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('BaseCoverageReport', 'TestSuite/Coverage');
 
+/**
+ * Generates code coverage reports in Simple plain text from data obtained from PHPUnit
+ *
+ * @package       Cake.TestSuite.Coverage
+ */
 class TextCoverageReport extends BaseCoverageReport {
 
 /**

lib/Cake/TestSuite/Fixture/CakeFixtureManager.php

@@ -16,9 +16,15 @@
  * @since         CakePHP(tm) v 2.0
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('ConnectionManager', 'Model');
 App::uses('ClassRegistry', 'Utility');
 
+/**
+ * A factory class to manage the life cycle of test fixtures
+ *
+ * @package       Cake.TestSuite.Fixture
+ */
 class CakeFixtureManager {
 
 /**

lib/Cake/TestSuite/Fixture/CakeTestFixture.php

@@ -1,9 +1,5 @@
 <?php
 /**
- * Short description for file.
- *
- * PHP 5
- *
  * CakePHP(tm) Tests <http://book.cakephp.org/view/1196/Testing>
  * Copyright 2005-2011, Cake Software Foundation, Inc. (http://cakefoundation.org)
  *
@@ -16,10 +12,12 @@
  * @since         CakePHP(tm) v 1.2.0.4667
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('CakeSchema', 'Model');
 
 /**
- * Short description for class.
+ * CakeTestFixture is responsible for building and destroying tables to be used 
+ * during testing.
  *
  * @package       Cake.TestSuite.Fixture
  */

lib/Cake/TestSuite/Fixture/CakeTestModel.php

@@ -1,9 +1,5 @@
 <?php
 /**
- * Short description for file.
- *
- * PHP 5
- *
  * CakePHP(tm) Tests <http://book.cakephp.org/view/1196/Testing>
  * Copyright 2005-2011, Cake Software Foundation, Inc. (http://cakefoundation.org)
  *
@@ -20,7 +16,7 @@
 App::uses('Model', 'Model');
 
 /**
- * Short description for class.
+ * A model to extend from to help you during testing.
  *
  * @package       Cake.TestSuite.Fixture
  */

lib/Cake/Utility/Debugger.php

@@ -19,10 +19,6 @@
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 
-/**
- * Included libraries.
- *
- */
 App::uses('CakeLog', 'Log');
 App::uses('String', 'Utility');
 

lib/Cake/Utility/File.php

@@ -17,10 +17,6 @@
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 
-/**
- * Included libraries.
- *
- */
 App::uses('Folder', 'Utility');
 
 /**

lib/Cake/Utility/ObjectCollection.php

@@ -10,6 +10,7 @@
  * @link          http://cakephp.org CakePHP(tm) Project
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 /**
  * Deals with Collections of objects.  Keeping registries of those objects,
  * loading and constructing new objects and triggering callbacks. Each subclass needs

lib/Cake/Utility/Sanitize.php

@@ -18,6 +18,7 @@
  * @since         CakePHP(tm) v 0.10.0.1076
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::import('Model', 'ConnectionManager');
 
 /**

lib/Cake/Utility/Xml.php

@@ -19,6 +19,13 @@
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 
+/**
+ * XML handling for Cake.
+ *
+ * The methods in these classes enable the datasources that use XML to work.
+ *
+ * @package       Cake.Utility
+ */
 class Xml {
 
 /**

lib/Cake/View/Helper/AppHelper.php

@@ -19,6 +19,7 @@
  * @since         CakePHP(tm) v 0.2.9
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('Helper', 'View');
 
 /**

lib/Cake/View/Helper/JqueryEngineHelper.php

@@ -26,6 +26,17 @@
 App::uses('AppHelper', 'View/Helper');
 App::uses('JsBaseEngineHelper', 'View/Helper');
 
+/**
+ * jQuery Engine Helper for JsHelper
+ *
+ * Provides jQuery specific Javascript for JsHelper.
+ *
+ * Implements the JsHelper interface for jQuery.  All $options arrays
+ * support all options found in the JsHelper, as well as those in the jQuery
+ * documentation.
+ *
+ * @package       Cake.View.Helper
+ */
 class JqueryEngineHelper extends JsBaseEngineHelper {
 /**
  * Option mappings for jQuery

lib/Cake/View/Helper/MootoolsEngineHelper.php

@@ -27,6 +27,19 @@
 
 App::uses('JsBaseEngineHelper', 'View/Helper');
 
+/**
+ * MooTools Engine Helper for JsHelper
+ *
+ * Provides MooTools specific Javascript for JsHelper.
+ * Assumes that you have the following MooTools packages
+ *
+ * - Remote, Remote.HTML, Remote.JSON
+ * - Fx, Fx.Tween, Fx.Morph
+ * - Selectors, DomReady,
+ * - Drag, Drag.Move
+ *
+ * @package       Cake.View.Helper
+ */
 class MootoolsEngineHelper extends JsBaseEngineHelper {
 /**
  * Option mappings for MooTools

lib/Cake/View/Helper/PrototypeEngineHelper.php

@@ -22,6 +22,14 @@
 
 App::uses('JsBaseEngineHelper', 'View/Helper');
 
+/**
+ * Prototype Engine Helper for JsHelper
+ *
+ * Provides Prototype specific Javascript for JsHelper. Requires at least
+ * Prototype 1.6
+ *
+ * @package       Cake.View.Helper
+ */
 class PrototypeEngineHelper extends JsBaseEngineHelper {
 /**
  * Is the current selection a multiple selection? or is it just a single element.

lib/Cake/View/Helper/TextHelper.php

@@ -19,10 +19,6 @@
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 
-/**
- * Included libraries.
- *
- */
 App::uses('AppHelper', 'View/Helper');
 App::uses('HtmlHelper', 'Helper');
 App::uses('Multibyte', 'I18n');

lib/Cake/View/Helper/TimeHelper.php

@@ -16,6 +16,7 @@
  * @since         CakePHP(tm) v 0.10.0.1076
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('Multibyte', 'I18n');
 App::uses('AppHelper', 'View/Helper');
 

lib/Cake/View/HelperCollection.php

@@ -18,6 +18,12 @@
 
 App::uses('ObjectCollection', 'Utility');
 
+/**
+ * Helpers collection is used as a registry for loaded helpers and handles loading
+ * and constructing helper class objects.
+ *
+ * @package       Cake.View
+ */
 class HelperCollection extends ObjectCollection {
 
 /**

lib/Cake/View/MediaView.php

@@ -16,6 +16,7 @@
  * @since         CakePHP(tm) v 1.2.0.5714
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('View', 'View');
 App::uses('CakeRequest', 'Network');
 

lib/Cake/View/ScaffoldView.php

@@ -18,6 +18,7 @@
  * @since         Cake v 0.10.0.1076
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('ThemeView', 'View');
 
 /**

lib/Cake/View/ThemeView.php

@@ -16,6 +16,7 @@
  * @since         CakePHP(tm) v 0.10.0.1076
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+
 App::uses('View', 'View');
 
 /**

lib/Cake/View/View.php

@@ -17,9 +17,6 @@
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 
-/**
- * Included libraries.
- */
 App::uses('HelperCollection', 'View');
 App::uses('AppHelper', 'View/Helper');
 App::uses('Router', 'Routing');