Issue #2216543 by jhodgdon, Berdir: Fill in topic/@defgroup docs for Cache overview.

core/lib/Drupal.php

@@ -225,6 +225,8 @@ public static function database() {
    *
    * @return \Drupal\Core\Cache\CacheBackendInterface
    *   The cache object associated with the specified bin.
+   *
+   * @ingroup cache
    */
   public static function cache($bin = 'cache') {
     return static::$container->get('cache.' . $bin);

core/lib/Drupal/Core/Cache/BackendChain.php

@@ -19,6 +19,8 @@
  * volatile backend but found in the persistent one will be propagated back up
  * to ensure fast retrieval on the next request. On cache sets and deletes, both
  * backends will be invoked to ensure consistency.
+ *
+ * @ingroup cache
  */
 
 class BackendChain implements CacheBackendInterface {

core/lib/Drupal/Core/Cache/Cache.php

@@ -9,6 +9,8 @@
 
 /**
  * Helper methods for cache.
+ *
+ * @ingroup cache
  */
 class Cache {
 

core/lib/Drupal/Core/Cache/CacheBackendInterface.php

@@ -14,60 +14,7 @@
  * Drupal\Core\Cache\DatabaseBackend provides the default implementation, which
  * can be consulted as an example.
  *
- * To make Drupal use your implementation for a certain cache bin, you have to
- * set a variable with the name of the cache bin as its key and the name of
- * your class as its value. For example, if your implementation of
- * Drupal\Core\Cache\CacheBackendInterface was called MyCustomCache, the
- * following line would make Drupal use it for the 'cache_page' bin:
- * @code
- *  $settings['cache_classes']['cache_page'] = 'MyCustomCache';
- * @endcode
- *
- * Additionally, you can register your cache implementation to be used by
- * default for all cache bins by setting the $settings['cache_classes'] variable and
- * changing the value of the 'cache' key to the name of your implementation of
- * the Drupal\Core\Cache\CacheBackendInterface, e.g.
- * @code
- *  $settings['cache_classes']['cache'] = 'MyCustomCache';
- * @endcode
- *
- * To implement a completely custom cache bin, use the same variable format:
- * @code
- *  $settings['cache_classes']['custom_bin'] = 'MyCustomCache';
- * @endcode
- * To access your custom cache bin, specify the name of the bin when storing
- * or retrieving cached data:
- * @code
- *  \Drupal::cache('custom_bin')->set($cid, $data, $expire);
- *  \Drupal::cache('custom_bin')->get($cid);
- * @endcode
- *
- * There are two ways to "remove" a cache item:
- * - Deletion (using delete(), deleteMultiple(), deleteTags() or deleteAll()):
- *   Permanently removes the item from the cache.
- * - Invalidation (using invalidate(), invalidateMultiple(), invalidateTags()
- *   or invalidateAll()): a "soft" delete that only marks the items as
- *   "invalid", meaning "not fresh" or "not fresh enough". Invalid items are
- *   not usually returned from the cache, so in most ways they behave as if they
- *   have been deleted. However, it is possible to retrieve the invalid entries,
- *   if they have not yet been permanently removed by the garbage collector, by
- *   passing TRUE as the second argument for get($cid, $allow_invalid).
- *
- * Cache items should be deleted if they are no longer considered useful. This
- * is relevant e.g. if the cache item contains references to data that has been
- * deleted. On the other hand, it may be relevant to just invalidate the item
- * if the cached data may be useful to some callers until the cache item has
- * been updated with fresh data. The fact that it was fresh a short while ago
- * may often be sufficient.
- *
- * Invalidation is particularly useful to protect against stampedes. Rather than
- * having multiple concurrent requests updating the same cache item when it
- * expires or is deleted, there can be one request updating the cache, while
- * the other requests can proceed using the stale value. As soon as the cache
- * item has been updated, all future requests will use the updated value.
- *
- * @see \Drupal::cache()
- * @see \Drupal\Core\Cache\DatabaseBackend
+ * @ingroup cache
  */
 interface CacheBackendInterface {
 

core/lib/Drupal/Core/Cache/CacheCollector.php

@@ -22,6 +22,8 @@
  * CacheCollector->has() needs to correctly return (equivalent to
  * array_key_exists() vs. isset()). This should not be necessary in the majority
  * of cases.
+ *
+ * @ingroup cache
  */
 abstract class CacheCollector implements CacheCollectorInterface, DestructableInterface {
 

core/lib/Drupal/Core/Cache/CacheCollectorInterface.php

@@ -18,6 +18,8 @@
  * request, and memory usage from static caches of that same data.
  *
  * The default implementation is \Drupal\Core\Cache\CacheCollector.
+ *
+ * @ingroup cache
  */
 interface CacheCollectorInterface {
 

core/lib/Drupal/Core/Cache/CacheableInterface.php

@@ -8,6 +8,8 @@
 
 /**
  * Defines an interface for objects which are potentially cacheable.
+ *
+ * @ingroup cache
  */
 interface CacheableInterface {
 

core/lib/Drupal/Core/Cache/DatabaseBackend.php

@@ -15,6 +15,8 @@
  *
  * This is Drupal's default cache implementation. It uses the database to store
  * cached data. Each cache bin corresponds to a database table by the same name.
+ *
+ * @ingroup cache
  */
 class DatabaseBackend implements CacheBackendInterface {
 

core/lib/Drupal/Core/Cache/MemoryBackend.php

@@ -15,6 +15,7 @@
  * Should be used for unit tests and specialist use-cases only, does not
  * store cached items between requests.
  *
+ * @ingroup cache
  */
 class MemoryBackend implements CacheBackendInterface {
 

core/lib/Drupal/Core/Cache/NullBackend.php

@@ -17,6 +17,8 @@
  * operations would have a negative impact on performance.
  *
  * This also can be used for testing purposes.
+ *
+ * @ingroup cache
  */
 class NullBackend implements CacheBackendInterface {
 

core/modules/system/core.api.php

@@ -173,10 +173,142 @@
  * @{
  * Information about the Drupal Cache API
  *
- * @todo write this
- *
- * Additional documentation paragraphs need to be written, and functions,
- * classes, and interfaces need to be added to this topic.
+ * @section basics Basics
+ *
+ * Note: If not specified, all of the methods mentioned here belong to
+ * \Drupal\Core\Cache\CacheBackendInterface.
+ *
+ * The Cache API is used to store data that takes a long time to
+ * compute. Caching can be permanent, temporary, or valid for a certain
+ * timespan, and the cache can contain any type of data.
+ *
+ * To use the Cache API:
+ * - Request a cache object through \Drupal::cache() or by injecting a cache
+ *   service.
+ * - Define a Cache ID (cid) value for your data. A cid is a string, which must
+ *   contain enough information to uniquely identify the data. For example, if
+ *   your data contains translated strings, then your cid value must include the
+ *   current interface language.
+ * - Call the get() method to attempt a cache read, to see if the cache already
+ *   contains your data.
+ * - If your data is not already in the cache, compute it and add it to the
+ *   cache using the set() method. The third argument of set() can be used to
+ *   control the lifetime of your cache item.
+ *
+ * Example:
+ * @code
+ * $cache = \Drupal::cache();
+ * $cid = 'mymodule_example:' . \Drupal::languageManager()->getCurrentLanguage()->id();
+ *
+ * $data = NULL;
+ * if ($cache = \Drupal::cache()->get($cid)) {
+ *   $data = $cache->data;
+ * }
+ * else {
+ *   $data = my_module_complicated_calculation();
+ *   \Drupal::cache()->set($cid, $data);
+ * }
+ * @endcode
+ *
+ * @section bins Cache bins
+ *
+ * Cache storage is separated into "bins", each containing various cache items.
+ * Each bin can be configured separately; see @ref configuration.
+ *
+ * When you request a cache object, you can specify the bin name in your call to
+ * \Drupal::cache(). Alternatively, you can request a bin by getting service
+ * "cache.nameofbin" from the container. The default bin is called "cache", with
+ * service name "cache.cache".
+ *
+ * @todo: Document common cache bins in https://drupal.org/node/1194136
+ *
+ * A module can define a cache bin by defining a service in its
+ * modulename.services.yml file as follows (substituting the desired name for
+ * "nameofbin"):
+ * @code
+ * cache.nameofbin:
+ *   class: Drupal\Core\Cache\CacheBackendInterface
+ *   tags:
+ *     - { name: cache.bin }
+ *   factory_method: get
+ *   factory_service: cache_factory
+ *   arguments: [nameofbin]
+ * @endcode
+ *
+ * @section delete Deletion
+ *
+ * There are two ways to remove an item from the cache:
+ * - Deletion (using delete(), deleteMultiple() or deleteAll()) permanently
+ *   removes the item from the cache.
+ * - Invalidation (using invalidate(), invalidateMultiple() or invalidateAll())
+ *   is a "soft" delete that only marks items as "invalid", meaning "not fresh"
+ *   or "not fresh enough". Invalid items are not usually returned from the
+ *   cache, so in most ways they behave as if they have been deleted. However,
+ *   it is possible to retrieve invalid items, if they have not yet been
+ *   permanently removed by the garbage collector, by passing TRUE as the second
+ *   argument for get($cid, $allow_invalid).
+ *
+ * Use deletion if a cache item is no longer useful; for instance, if the item
+ * contains references to data that has been deleted. Use invalidation if the
+ * cached item may still be useful to some callers until it has been updated
+ * with fresh data. The fact that it was fresh a short while ago may often be
+ * sufficient.
+ *
+ * Invalidation is particularly useful to protect against stampedes. Rather than
+ * having multiple concurrent requests updating the same cache item when it
+ * expires or is deleted, there can be one request updating the cache, while the
+ * other requests can proceed using the stale value. As soon as the cache item
+ * has been updated, all future requests will use the updated value.
+ *
+ * @section tags Cache Tags
+ *
+ * The fourth argument of the set() method can be used to specify cache tags,
+ * which are used to identify what type of data is included in each cache. Each
+ * cache can have multiple tags, and each tag has a string key and a value. The
+ * value can be:
+ * - TRUE, to indicate that this type of data is present in the cache.
+ * - An array of values. For example, the "node" tag indicates that particular
+ *   nodes' data is present in the cache, so its value is an array of node IDs.
+ * Data that has been tagged can be deleted or invalidated as a group.
+ *
+ * Example:
+ * @code
+ * // A cache item with nodes, users, and some custom module data.
+ * $tags = array(
+ *   'my_custom_tag' => TRUE,
+ *   'node' => array(1, 3),
+ *   'user' => array(7),
+ * );
+ * \Drupal::cache()->set($cid, $data, CacheBackendInterface::CACHE_PERMANENT, $tags);
+ *
+ * // Delete or invalidate all caches with certain tags.
+ * \Drupal\Core\Cache\Cache::deleteTags(array('node' => array(1));
+ * \Drupal\Core\Cache\Cache::invalidateTags(array('user' => array(1)));
+ * @endcode
+ *
+ * @todo Update cache tag deletion in https://drupal.org/node/918538
+ *
+ * @todo Extend entity cache tags based on https://drupal.org/node/2217749
+ *
+ * @section configuration Configuration
+ *
+ * Each cache bin can be configured separately; for instance, each bin can use a
+ * different cache backend, such as APC or Memcache. The default backend stores
+ * the cached data in the Drupal database.
+ *
+ * In a settings.php file, you can override the class used for a particular
+ * cache bin. For example, if your implementation of
+ * \Drupal\Core\Cache\CacheBackendInterface was called MyCustomCache, the
+ * following line would make Drupal use it for the 'cache_page' bin:
+ * @code
+ *  $settings['cache_classes']['cache_page'] = 'Drupal\full\namespace\to\MyCustomCache';
+ * @endcode
+ *
+ * Additionally, you can register your cache implementation to be used by
+ * default for all cache bins with:
+ * @code
+ *  $settings['cache_classes']['cache'] = 'Drupal\full\namespace\to\MyCustomCache';
+ * @endcode
  *
  * @see https://drupal.org/node/1884796
  * @}