Rewrite docs for EntityAutocomplete and DefaultSelection to make clear what config properties are used

This issue is being reviewed by the kind folks in Slack, #needs-review-queue-initiative. We are working to keep the size of Needs Review queue [2700+ issues] to around 400 (1 month or less), following Review a patch or merge request → as a guide.

Documentation change looks like a good improvement.

Always nice to see documentation improvements.

+++ b/core/lib/Drupal/Core/Entity/Plugin/EntityReferenceSelection/DefaultSelection.php
@@ -25,6 +25,18 @@
+ * Plugin configuration must contain a key handler_settings referencing an

The first thing I noticed in this documentation was a double space. Then, I thought 'handler_settings' should be in quotes but then, as I read this, I think we can do better here. The descriptions should start with what the key is for, not the default value. And the reader should know what keys are required and which ones are optional, using the standard format. It is easier to express my ideas by example so I made a suggestion.

 * Available configuration keys.
 * - handler_settings: (required) An array with the following keys.
 *   - auto_create: (?) If TRUE, create referenced entities
 *     if they don't already exist. Defaults to FALSE.
 *   - auto_create_bundle: (?) Bundle name for auto-created entities, if
 *     auto-create is TRUE. Defaults to NULL.
 *   - sort: (?) An array of sort parameters. Default to ['field' => '_none'].
 *   - target_bundles: (?) An array of bundle names. Defaults to NULL. NULL means
 *     "allow entities from any bundle to be referenced"; an empty array
 *     means "no entities from any bundle can be referenced".
 *

There is still work to do here. The text '(?)' needs to be replaced with (optional) or (required). And, maybe the description for target_bundles needs a tweak as well. It is not obvious why the two phrases are in double quotes.

See Making lists in documentation →

target_bundles, sort, auto_create, auto_create_bundle are optional, since they default to something in defaultConfiguration().

> * - sort: (?) An array of sort parameters. Default to ['field' => '_none'].

We should say it's an array containing 'field' - the field name to sort on and 'direction' - one of ASC/DEC.

Also, auto_create_bundle MUST be specified if auto_create is TRUE.