Issue #3361695 by tunic, smustgrave, lauriii, quietone, borisson_: Fix the...

Issue #3361695 by tunic, smustgrave, lauriii, quietone, borisson_: Fix the documentation for #empty_value on Drupal\Core\Render\Element\Select

core/lib/Drupal/Core/Render/Element/Select.php

@@ -41,7 +41,11 @@
  *   field and "- None -" for an optional field.
  * - #empty_value: (optional) The value for the first default option, which is
  *   used to determine whether the user submitted a value or not.
- *   - If #required is TRUE, this defaults to '' (an empty string).
+ *   - If #required is TRUE, this defaults to '' (an empty string). Note that
+ *     if #empty_value is the same as a key in #options then the value of
+ *     #empty_option is used for that key in the #options array. This is
+ *     because #empty_value and #empty_option are merged into the #options
+ *     array. Hence, make sure #empty_value is not a key in #options array.
  *   - If #required is not TRUE and this value isn't set, then no extra option
  *     is added to the select control, leaving the control in a slightly
  *     illogical state, because there's no way for the user to select nothing,