Fix the documentation for #empty_value on Drupal\Core\Render\Element\Select

Please ignore the 10.1.x, I pushed there by mistake. The same fix is in the 3361695-fix-the-documentation branch.

Additionally, should the Form API or render system detect this problem and raise a waring? Some kind of render/form API array structure validation

Thanks for the review, typo fixed and branch rebased so it's mergeable again.

Ouch! I'm trying a new IDE and I've discovered it is not configured for Drupal coding standards. Sorry for the noise.

#12, I think it is interesting to automatically check that the issue is not happening (aka #options value overriden by #empty_value if #empty_option is present in #options), but I'm not sure how to do it.

Using assert will only work when assertions are enabled. This can be the case for automatic testing but it is not on production environments. Given the dynamic nature of forms, it is possible that the case where #options is overriden only happens on certain situations. This would not be detected by testing. And having a fatal error can be too drastic, I guess.

I would check the condition and raise a warning. This way Drupal is able to continue running, even though there's probably a problem. Any devs checking the logs or debugging a weird behavior on a form will see error.

But this discussion can ne longer, and the initial issue is about documentation. I think we should focus this issue on the documentation and open a new one for the warning where we can discuss how to do it.

Follow up added: #3375072: Add an exception/warning/assert/other when a #options value is overriden because #empty_options.

#16, it may work as designed, but the behavior doesn't seem right, hence the warning. See https://www.drupal.org/project/documentation/issues/1936636#comment-1505... for an example.

However, I think 'Note' would work. If it is preferred I won't complain, but I would like to have a decision soon so we can fix the MR with the agreed value.

Changed "Warning: " by "Note that" (with an intermediate commit where I wrongly used "Note: ")

PHPStan step has been executed successfully.

@laurii I guess you mean more details in the sentence are required on the proposed sentence.

This is the current sentence:

Note that if #empty_value is the same as a key in #options then that value in #options is overridden with the value of #empty_option

Would it be clear with this?

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.

Also, I guess the status should be "Needs work" instead of "Needs review", right?

I stumbled upon this issue again. I've tried to better explain the situation to address #28:

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 this is not enough, please point out what is missing or what would be a better approach to this. The issue is complex and it is hard to understand without a little bit of context or checking all the comments in the class' header.