Fill in topic/@defgroup docs for Cache overview

Starting this..

There is some documentation on CacheBackendInterface right now, but this is a better place for it. Added some @section's, otherwise it's 1:1 copy. And while there's extensive documentation on how to configure a custom cache backend and deletion, there's nothing about the "normal usage".

Someone else is probably more qualified to start writing something there, so posting this as an intermediate step...

c) I would assume that basics should come first, tags probably deserve their own section too.

d) True. But expanding that to Drupal\Core\Cache\CacheBackendInterface::delete() and so on would also be far less readable.

Ok, spent some more time on writing additional documentation and re-structuring a bit :)

Tried to address the feedback as much as possible, for d), I added a note about the location of the methods at the top, I don't think we should repeat that for every section?

Added a @todo's with issues that I know about that will affect ths.

Thanks, changes look good.

Assigning to @webchick per @jhodgdon's suggestion, as she worked on it a bit too.

+++ b/core/modules/system/core.api.php
@@ -173,10 +173,142 @@
+ * \Drupal\Core\Cache\CacheBackendInterface.
...
+ * - Request a cache object through \Drupal::cache() or by injecting a cache
...
+ * - Define a Cache ID (cid) value for your data. A cid is a string, which must
...
+ * - Call the get() method to attempt a cache read, to see if the cache already
...
+ *   cache using the set() method. The third argument of set() can be used to

Will all of the code terms (function names and "cid") be wrapped in code tags?

I think that's essential for legibility of docs.

Are there then at least plans to do so? It seems that since we have https://api.drupal.org/api/drupal/8, https://drupal.org/documentation will become less important, because most docs will live at https://api.drupal.org/api/drupal/8 instead. If none of that has the proper formatting, then that's a huge regression.

Committed and pushed to 8.x. Thanks!

Shoot. I was just about to add some comments to this one. Here they are:

+ * 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);
+ * }

This code seems wrong. We create the $cache object in the first line, but never use it. Then recreate it in the if statement. Seems like maybe the if statement should use $cache->get() instead? Lets make sure this is right and reflects best practices because people are going to copy/paste this example like crazy if it's in the docs.

+ * @section bins Cache bins
+ *
+ * Cache storage is separated into "bins", each containing various cache items.
+ * Each bin can be configured separately; see @ref configuration.

It would be nice to have a better explination of why there are different cache bins and how I should decide when to use the default vs. another existing option vs. creating my own. Though perhaps this is something better for a handbook page? In which case we should create the stub of that page and link to it from here.

+ * 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.

I find this a little confusing and think it would benefit from changing the order of statements. I think changing the backend of the entire system is likely more common than changing and individual bin. What about something like:

"By default cached data is stored in the database. This can be configured though so that all cached data, or that of an individual cache bin, uses a different cache backend, such as APC or Memcache, for storage."

I'm going to re-open this because at a minimum we should confirm that that code sample is correct. If it is and I'm just missing something feel free to tell me to stop being silly. :)

the only thing that's wrong about the code is the initial $cache definition, I forgot to remove that.

It would be nice to have a better explination of why there are different cache bins and how I should decide when to use the default vs. another existing option vs. creating my own. Though perhaps this is something better for a handbook page? In which case we should create the stub of that page and link to it from here.

That is what I added the @todo to the re-organize cache bins issue (#1194136: Re-organise core cache bins). Documenting it right now not make sense as that issue will change a lot there.

Here's a patch that:

1. Removes the unnecessary $cache = line of code from the example.

2. Adds some clarification about the use of $cache->data & $data variables.

3. Rewords the paragraph in the configuration section that was a little bit confusing.

Thanks for taking care of that other @todo in #1194136: Re-organise core cache bins. I like that part now. :)

Thanks, looks good. We have an issue to make the returned object a typed object with an interface/methods, but that got sidetracked on different things...