More documentation for Cache.

cake/libs/cache.php

@@ -71,14 +71,24 @@ class Cache {
  * both create new configurations, return the settings for already configured
  * configurations.
  *
- * To create a new configuration:
+ * To create a new configuration, or to modify an existing configuration permanently:
  *
  * `Cache::config('my_config', array('engine' => 'File', 'path' => TMP));`
  *
- * To get the settings for a configuration, and set it as the currently selected configuration
+ * If you need to modify a configuration temporarily, use Cache::set().
+ * To get the settings for a configuration:
  *
  * `Cache::config('default');`
  *
+ * There are 4 built-in caching engines:
+ *
+ * - `FileEngine` - Uses simple files to store content. Poor performance, but good for
+ *    storing large objects, or things that are not IO sensitive.
+ * - `ApcEngine` - Uses the APC object cache, one of the fastest caching engines.
+ * - `MemcacheEngine` - Uses the PECL::Memcache extension and Memcached for storage.
+ *   Fast reads/writes, and benefits from memcache being distributed.
+ * - `XcacheEngine` - Uses the Xcache extension, an alternative to APC.
+ *
  * @see app/config/core.php for configuration settings
  * @param string $name Name of the configuration
  * @param array $settings Optional associative array of settings passed to the engine

cake/libs/cache/file.php

@@ -1,7 +1,10 @@
 <?php
 /**
- * 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()
  *
  * PHP 5
  *