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

@Tronux thanks for this. I think you're right, that the properties in the settings and element arrays being passed around aren't clear. There is actually documentation of $element properties on this class, but it's buried down in one of the static method docblocks. Also, the sub-properties of $element['#selection_settings'] are not clearly explained anywhere.

Based on this ticket and discussion here https://api.drupal.org/comment/62553#comment-62553 , I attach a patch which modifies two classes:

EntityAutocomplete

Move the documentation for what $element might contain, up to the top of the class, and improve method docblocks on the way. Reference the below class for more information of the sub-properties of handler_settings.

DefaultSelection

Make explicit the documentation of default properties on the handler_settings configuration, so these don't have to be documented in the previous.

Both

Add a @see ... so each class references the other.

Feedback welcome!

This all makes sense.

Having the @see references and moving the target_bundles to the main body of the comment is very helpful.

Thanks, RTBC.

I'd like to see an issue title that describes the documentation deficiency and an issue summary that reflects the direction of the patch in #2.

Looking at this now.

@cilefen thanks: you're right that the problem @tronux kindly originally reported, pointed away from the ultimate fix (it referenced a solution in another class, that was actually a red herring, just coincidentally describing the same config property.)

Out of interest, I see a few issue summaries beginning "Enter a descriptive title (above) relating to class EntityAutocomplete, then describe the problem you have found:" and they're often in need of a tidyup. Is that coming from a particular submission channel? I don't know if that could be improved to get better summaries from reporters, or whether that would be intimidating; maybe a summary that needs tidying is better than no summary at all.

Anyway, I've used the standard issue template to reword the description now, and redrafted the title. Would appreciate a re-review.

Re-rolled from #2

The most recent patches are losing a lot of the changes from patch #2.

Here is the rerolled patch from #2, thanks!

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.