Document cacheability of render arrays, and the considerations to use when generating render arrays

Because contributed modules that do this wrong will undo all the ground work in core

1. +++ b/core/modules/system/core.api.php
   @@ -372,9 +372,25 @@
   + * The most important thing to know and remember while caching things is the
   

   I think we need examples of each of the three here - an example aids clarity.

2. +++ b/core/modules/system/core.api.php
   @@ -372,9 +372,25 @@
   + * 2. cache contexts: an array of contexts that indicate the context in which
   + *    the representation of the thing (see 1.) is being viewed. Simply put: the
   + *    state of the viewer (which user, which language, which country …) that
   + *    requires a specific variation of the thing.
   

   The thing that drove this home for me a.k.a. the Eureka moment, was someone somewhere telling me these were analogous to 'Vary' headers - should we add that here as it's a valid point of reference.

The thing that drove this home for me a.k.a. the Eureka moment, was someone somewhere telling me these were analogous to 'Vary' headers

+ a lot to that. TBH, not sure why we named that "context" rather than "vary" :-)

Yeah, agreed that "vary" makes it harder to make actual sentences with :-/. "Vary context" ?

+++ b/core/modules/system/core.api.php
@@ -372,9 +372,25 @@
  * - Request a cache object through \Drupal::cache() or by injecting a cache
  *   service.
+ * - Define cache keys
  * - 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

I'm still confused by cache keys vs cache ID (I think keys should really by cid_parts or something) but this doesn't make sense. AFAIK, having a cid will ignore any cache keys, so you need to have either one and usually cache keys.

Anyway, sounds like this line is cut of/incomplete anyway..

I recently saw something that I wanted to comment here about, something that would be important to document here as well, but I can't remember... :(

+++ b/core/modules/system/theme.api.php
@@ -287,6 +287,74 @@
+ *   regenerated. So my cache tags would be: ['node:5', 'user:3', 'file:4',
+ *   'config:filter.format.basic_html'].

This currently seems to imply that I need to set them all myself.

I think its important to distinguish when to add what in another example.

--

Besides this, this is good to go :).

RTBC, These are great examples!

- * $build['#attached']['drupalSettings']['foo] = 'bar';
+ * $build['#attached']['drupalSettings']['foo'] = 'bar';

I didn't see this sneaking in...

1. +++ b/core/modules/system/theme.api.php
   @@ -287,6 +287,134 @@
   + * Since the contents of a render array determine what is shown to the user, it
   + * also depends on render arrays "how cacheable" a page is. If your code is
   

   Does how cacheable need to be in quotes. Also I think the first sentence reads better like Render arrays determine what is shown to the user. Therefore, render arrays also determine how cacheable a response is. Also it might not be "your" code.

2. +++ b/core/modules/system/theme.api.php
   @@ -287,6 +287,134 @@
   + *    representation of the thing I'm rendering?
   + *    Those are the cache keys.
   + *    They're only necessary if I want to cache this render array.
   ...
   + *    so should my representation?
   + *    Those are the cache tags.
   + *    They're always necessary, because they affect the cacheability of the
   

   Formatting is a bit weird here - seems to be deliberately not flowing to 80 chars. Is this for readability?

3. +++ b/core/modules/system/theme.api.php
   @@ -287,6 +287,134 @@
   + * - cache keys identify a representation of a thing
   + *   - may only be set if this render array should be cached
   + *   - will trigger caching of this render array (subtree)
   

   Is it worth having an example where cache keys are set?

@alexpott asked me to take a look at this patch. It seems kind of OK, but it's overly wordy and has way to many Exclamation Points!!! Let's Not Use Those In Docs!

So, I rewrote it. I didn't bother with an interdiff file, since it would be twice as big as the new patch.

Well, this still needs a rewrite. I can't review it today, sorry.

OK, here's a quick review... Basically, the proposed documentation in the latest patch is too wordy and too conversational and not very documentation-like.... Put more information on drupal.org if you want and link there, and be conversational in a blog post, but this is meant to be a short overview in a straightforward documentation style. Some specific suggestions:

a) No blank line after the @section line.

b) This is documentation that is going inside the Theme and Render System topic on api.drupal.org. These topics need to be concise and not repeat each other. So, this documentation should not:
- Explain what caching is or why it is desirable. Link to the Cache topic instead.
- Repeat itself at all. No "In other words" paragraphs. Just state the facts once.
- Talk about "importance" of doing stuff or "must". Just state what developers should do in a clear and concise manner.
- Give more than one example. One is enough. Make a page on drupal.org if you want to do more, and link there if necessary, but this is way too much for this topic.

c) The whole thing is very "conversational". We want it to match the style of the rest of the documentation in the topics. And you still have an ! in the text. Please remove. As another example, the first "step" in the process is: "I'm rendering something". This is again the wrong style.

So... that's just a quick review... I think it would be better if you could go back to my patch and fix the factual error (you didn't point out what that was?). My patch is in the style and level of detail that we want to have in these topics, and the information removal was intentional.

Great, thanks! I'm fine with tree/subtree. Please go ahead and make that change.

Regarding style docs, see:
https://www.drupal.org/style-guide/content

Patch is looking good, and the drupal.org page is great! A couple of nitpicks in the patch:

a)

+ * this property, always supply the cache contexts, tags and max-age. Cache keys

Serial comma needed in "... tags, and max-age". Appears again later in the paragraph too.

b) Actually, in place of "max-age" can we spell out "maximum age"? Unless "max-age" is what you'd actually use as an array key... what exactly is the array key for this anyway? Maybe it would help if we at least had an example of a #context array you could supply? I think that might be considered part of the "minimal" information that documentation on api.drupal.org should have.

c) I think we need to have something more about cache keys here... or maybe just point out that this is documented on the Cache API page. Just saying they are "identifiers" seems a bit too vague. Again, a concrete example could help people understand what they need to do.

e) Regarding the maximum age, the docs say you should "always" supply it. Is that really true, given that there is a default?

+ * Cache information is provided in the #cache property in a render array. In
+ * this property, always supply the cache contexts, tags and max-age. Cache keys

Great, this is really looking good, thanks!

Very minor nitpicks now:

a)

+ * render array varies by context, depends on some modifiable data or depends
+ * on information that's only valid for a limited time, respectively. Cache keys

needs a serial comma before "or" here.

b)

+ * The cache contexts, tags and max-age will be propagated up the render array

and here needs a serial comma before "and".

c)

+ * @code
+ * $build = [
+ *   …,

This needs a prefixing line, and probably we can omit the ... part. How about just saying:

 * Here's an example of what a #cache property might contain:
 * @code
 *   '#cache' => [
 *     'keys' => ['entity_view', 'node', $node->id()],

(etc.)

That's it -- rest is very good!

No problem -- you're not alone on the serial comma.

This looks good to me, thanks!

Docs are frozen in beta. Committed c428646 and pushed to 8.0.x. Thanks!