From 017dbaa27324007eecec8d966d28648aa3bd8cf4 Mon Sep 17 00:00:00 2001
From: catch <catch@35733.no-reply.drupal.org>
Date: Fri, 31 Jul 2020 12:50:38 +0100
Subject: [PATCH] Issue #2994319 by Ramya Balasubramanian, mohrerao,
 virajrajankar, benjamindamron, hardikpandya, kalyansamanta, jhodgdon,
 msankhala, jungle, kkalaskar, dhirendra.mishra, joachim, longwave, amateescu,
 mradcliffe, alexpott, jcnventura: EntityAutocomplete form element has no docs
 on how to use it

(cherry picked from commit 27b38859c5718732d89b956e7e75bda13898be71)
---
 .../Entity/Element/EntityAutocomplete.php     | 50 ++++++++++++++++++-
 1 file changed, 48 insertions(+), 2 deletions(-)

diff --git a/core/lib/Drupal/Core/Entity/Element/EntityAutocomplete.php b/core/lib/Drupal/Core/Entity/Element/EntityAutocomplete.php
index 10421abaae..241ce456cb 100644
--- a/core/lib/Drupal/Core/Entity/Element/EntityAutocomplete.php
+++ b/core/lib/Drupal/Core/Entity/Element/EntityAutocomplete.php
@@ -14,8 +14,54 @@
 /**
  * Provides an entity autocomplete form element.
  *
- * The #default_value accepted by this element is either an entity object or an
- * array of entity objects.
+ * The autocomplete form element allows users to select one or multiple
+ * entities, which can come from all or specific bundles of an entity type.
+ *
+ * Properties:
+ * - #target_type: (required) The ID of the target entity type.
+ * - #tags: (optional) TRUE if the element allows multiple selection. Defaults
+ *   to FALSE.
+ * - #default_value: (optional) The default entity or an array of default
+ *   entities, depending on the value of #tags.
+ * - #selection_handler: (optional) The plugin ID of the entity reference
+ *   selection handler (a plugin of type EntityReferenceSelection). The default
+ *   value is the lowest-weighted plugin that is compatible with #target_type.
+ * - #selection_settings: (optional) An array of settings for the selection
+ *   handler. Settings for the default selection handler
+ *   \Drupal\Core\Entity\Plugin\EntityReferenceSelection\DefaultSelection are:
+ *   - target_bundles: Array of bundles to allow (omit to allow all bundles).
+ *   - sort: Array with 'field' and 'direction' keys, determining how results
+ *     will be sorted. Defaults to unsorted.
+ * - #autocreate: (optional) Array of settings used to auto-create entities
+ *   that do not exist (omit to not auto-create entities). Elements:
+ *   - bundle: (required) Bundle to use for auto-created entities.
+ *   - uid: User ID to use as the author of auto-created entities. Defaults to
+ *     the current user.
+ * - #process_default_value: (optional) Set to FALSE if the #default_value
+ *   property is processed and access checked elsewhere (such as by a Field API
+ *   widget). Defaults to TRUE.
+ * - #validate_reference: (optional) Set to FALSE if validation of the selected
+ *   entities is performed elsewhere. Defaults to TRUE.
+ *
+ * Usage example:
+ * @code
+ * $form['my_element'] = [
+ *  '#type' => 'entity_autocomplete',
+ *  '#target_type' => 'node',
+ *  '#tags' => TRUE,
+ *  '#default_value' => $node,
+ *  '#selection_handler' => 'default',
+ *  '#selection_settings' => [
+ *    'target_bundles' => ['article', 'page'],
+ *   ],
+ *  '#autocreate' => [
+ *    'bundle' => 'article',
+ *    'uid' => <a valid user ID>,
+ *   ],
+ * ];
+ * @endcode
+ *
+ * @see \Drupal\Core\Entity\Plugin\EntityReferenceSelection\DefaultSelection
  *
  * @FormElement("entity_autocomplete")
  */
-- 
GitLab