Issue #2994319 by Ramya Balasubramanian, mohrerao, virajrajankar, ben…

…jamindamron, 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)

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")
  */