Document core cache tags and contexts

+1

I know, I know, I know that many people have put in time making the documentation clearer. And more is added every day. But what exists now is not yet instructive enough or comprehensive enough.

As one example, as far as I know, every core context is listed in the handbook but they are not really explained.

Now, all that said, I don't know for sure why we need a core issue to track this, unless we are talking about adding documentation to the code. The handbook pages have discussions (example: https://www.drupal.org/node/2459039/discuss).

As a developer, I want to see a list of cache tags and contexts available to me

A list of cache tags does not make sense. If you have 1 million nodes, you have 1 million node cache tags. and so on.

All core cache contexts are listed at https://www.drupal.org/docs/8/api/cache-api/cache-contexts. Few contrib modules add their own cache contexts, but if you want to see those too, see that page's How to recognize, discover and create? section: basically just grep for cache_context.* in your D8 site's services.

Was it node_list? Or entity_list? Is there a cache tag for nodes by content type?

That's exactly what https://www.drupal.org/docs/8/api/cache-api/cache-tags explains: And for entity listings, there is EntityTypeInterface::getListCacheTags(), to ensure listings of a certain entity type are invalidated when entities of that type are created/updated/deleted..

As a developer looking at the documentation, I also wonder things like whether or not I can create my own cache tags and contexts and how I would go about doing so--but that may be a separate issue.

https://www.drupal.org/docs/8/api/cache-api/cache-tags + https://www.drupal.org/docs/8/api/cache-api/cache-contexts already explain this.

The cache API doc links to https://www.drupal.org/docs/8/api/cache-api/cache-contexts. I feel each could be better explained on the handbook page, closer to what is written in their respective classes. But, this discussion should move there.

Note the API doc also reads:

Hence, all you have to do to find all cache contexts you have available for use, is to go to the CacheContextInterface and use your IDE to find all of its implementations. (In PHPStorm: Type Hierarchy → Subtypes Hierarchy.)