Improve documentation of the state and key value API

Problem/Motivation

There is very little information on when and when not to use the state API vs key value and other data storage. Now that 📌 Use cache collector for state Needs review is committed, incorrect usage can lead to performance issues.

This is a follow-up issue to improve that documentation, both the generated API docs as well as documentation drupal.org

Starting points to improve the docs are the Recommended usage section on the new change record: https://www.drupal.org/node/3177901 → , as well as comment #148 of the state cache issue:

The thing is, we already have non-cached collections, that's every other collection stored in keyvalue storage. If you don't want to have it cached, use \Drupal::keyValue('yourmodule')->get('foo'), that's just a few extra characters (DI is a bit more involved with the factory). The only reason we'd bother with a cached and non-cached state version is it wasn't cached until now and there might be sites out there that have all kinds of things in there due to custom and maybe some contrib modules using it ways it's not really meant to be used.

Of course "the way it's meant to be used" is kind of being changed here, no existing documentation clearly says it should only be used for small bits of information and limited cases, it's just somewhat implied by the examples. Also, the fact that it uses the key value store and is "just" a specific key value collection and the key value API itself doesn't seem to be actually documented anywhere (except the query to get all keys on the documentation page). Neither on https://api.drupal.org/api/drupal/core%21core.api.php/group/info_types/10 nor is there a key value API on https://www.drupal.org/docs/develop/drupal-apis → , and https://www.drupal.org/docs/8/api/state-api/overview → (which I think is very confusing, especially the reset part).

Steps to reproduce

Proposed resolution

Remaining tasks

User interface changes

API changes

Data model changes

Release notes snippet