Document several form elements that have no docs

Can a newbie help in this issue?

@metzlerd: Definitely I want to work on this one. Sorry, I didn't know I have to assign this to myself. Can you tell me if you have already included any of them in your code? And please pardon me for not replying. I came back the same day to reply but I had some connectivity issues at that time so couldn't reply.
Regards,
Rakesh Verma

Thanks, I just completed my drupal ladder and my proposal for GSoC. I will start working on it by tonight.
Thanks a lot.

Go Testbot

Form elements miss documentation and code examples.

@metzlerd: Added the example code for language test. Please review.

Great piece of advice. Thanks alot. Working on it :)

@jhodgdon warn me about this issue while I was working on #2710287: Image button properties are not documented.

I did some changes to consistently use array() instead of [] for arrays. Also we are not using two spaces for example codes.

Also removed #value for image buttons since they are not used on those type of elements.

The interdiff is against #8 with the patch #12 applied on top it.

We should instead consistently use [] instead of array() for arrays. Thanks!

Consistently using [] instead of array().

Thanks for taking on this issue dagmar!! The latest patch is looking pretty good.

There are several things that still need to be fixed though:

1. +++ b/core/lib/Drupal/Core/Datetime/Element/Datelist.php
   @@ -10,6 +10,48 @@
     * Provides a datelist element.
   

   What is a "datelist" element? We could use a better description of what it does, and how it differs from a Datetime.

   Also probably need an @see to the Datetime element.

2. +++ b/core/lib/Drupal/Core/Datetime/Element/Datelist.php
   @@ -10,6 +10,48 @@
   + * Properties:
   + *   - #default_value: A DrupalDateTime object, adjusted to the proper local
   

   Formatting:

   The - for the list items should line up under the P in Properties. Everything is 2 spaces extra indented.

3. +++ b/core/lib/Drupal/Core/Datetime/Element/Datelist.php
   @@ -10,6 +10,48 @@
   + *     user input strings back into a new date object on submission. No timezone
   + *     adjustment is performed.
   

   This last sentence about time zone adjustment is confusing to me, after having read the docs for the #date_timezone property below.

   I think one of them is incorrect and they seem to contradict each other?

4. +++ b/core/lib/Drupal/Core/Datetime/Element/Datelist.php
   @@ -10,6 +10,48 @@
   + *   - #date_text_parts: Array of date parts that should be presented as
   

   Looking at where this came from... we've lost the information about which properties are required and which are optional.

   The optional ones should be written like this:

   - #data_part_order: (optional) Array of ...
   

   This comment also applies to other date/time elements!

5. +++ b/core/lib/Drupal/Core/Datetime/Element/Datelist.php
   @@ -10,6 +10,48 @@
   + *   - #date_increment: The increment to use for minutes and seconds, i.e.
   + *     '15' would show only :00, :15, :30 and :45. Defaults to 1 to show every
   + *     minute.
   

   i.e. in this sentence is incorrect. This happens a lot in documentation (people confuse i.e. and e.g.). So, we prefer not to use i.e. or e.g. at all -- we had an issue on this recently that cleaned out a bunch of them.

   So, instead of "i.e." here, let's say "for example".

   Also the punctuation is incorrect. There should be a ; before "for example" and a , after it.

   These comments also apply to other date/time elements!

6. +++ b/core/lib/Drupal/Core/Datetime/Element/Datetime.php
   @@ -10,6 +10,90 @@
     * Provides a datetime element.
   

   What is a "datetime" element? We could use a better description of what it does, and how it differs from a Datelist.

   Also probably need an @see to the Datelist element.

7. +++ b/core/lib/Drupal/Core/Datetime/Element/Datetime.php
   @@ -10,6 +10,90 @@
   + * Examples of possible configurations include:
   + *   HTML5 date and time:
   + *     #date_date_element = 'date';
   + *     #date_time_element = 'time';
   + *   HTML5 datetime:
   + *     #date_date_element = 'datetime';
   + *     #date_time_element = 'none';
   + *   HTML5 time only:
   + *     #date_date_element = 'none';
   + *     #date_time_element = 'time'
   + *   Non-HTML5:
   + *     #date_date_element = 'text';
   + *     #date_time_element = 'text';
   

   This is not going to format well on api.drupal.org unless it is made into a bullet list (precede each line with - and the lists can be nested).

   Also I think it would be better to put these examples after the description of what the properties are. Right here it is a bit confusing. Or better yet, combine it with the Usage example section (maybe make 2 examples). Or ... do we even need this?

8. +++ b/core/lib/Drupal/Core/Datetime/Element/Datetime.php
   @@ -10,6 +10,90 @@
   + * Properties:
   + *   - #default_value: A DrupalDateTime object, adjusted to the proper local
   

   Formatting: list elements - should line up under the P in Properties. Everything is indented 2 spaces too much.

9. +++ b/core/lib/Drupal/Core/Datetime/Element/Datetime.php
   @@ -10,6 +10,90 @@
   + *     user input strings back into a new date object on submission. No timezone
   + *     adjustment is performed.
   

   See note about timezones from the Datelist element above.

10. +++ b/core/lib/Drupal/Core/Datetime/Element/Datetime.php
    @@ -10,6 +10,90 @@
    + *   - #date_date_format: A date format string that describes the format that
    + *     should be displayed to the end user for the date. When using HTML5
    + *     elements the format MUST use the appropriate HTML5 format for that
    + *     element, no other format will work. See the format_date() function for a
    + *     list of the possible formats and HTML5 standards for the HTML5
    + *     requirements. Defaults to the right HTML5 format for the chosen element
    + *     if a HTML5 element is used, otherwise defaults to
    + *     entity_load('date_format', 'html_date')->getPattern().
    

    This section is very confusing.

    Also the format_date() function is deprecated, and it doesn't have the information that this documentation says to look at.

    And how do you use an HTML5 element? Very confusing.

11. +++ b/core/lib/Drupal/Core/Datetime/Element/Datetime.php
    @@ -10,6 +10,90 @@
    + *   - #date_date_element: The date element. Options are:
    

    Ah, here's the element. Consider maybe moving this up, since the date format property references this? Would be way less confusing.

    Anyway, this may need some more explanation. What is it talking about? I think it should probably be saying "The HTML element used for the date portion" or something like that?

12. +++ b/core/lib/Drupal/Core/Datetime/Element/Datetime.php
    @@ -10,6 +10,90 @@
    + *   - #date_date_callbacks: Array of optional callbacks for the date element.
    

    When are these callbacks called? What are their parameters and return values?

13. +++ b/core/lib/Drupal/Core/Datetime/Element/Datetime.php
    @@ -10,6 +10,90 @@
    + *   - #date_time_element: The time element. Options are:
    

    See notes on the date_date_element above.

14. +++ b/core/lib/Drupal/Core/Datetime/Element/Datetime.php
    @@ -10,6 +10,90 @@
    + *   - #date_time_format: A date format string that describes the format that
    

    See notes on date_date_format above.

15. +++ b/core/lib/Drupal/Core/Datetime/Element/Datetime.php
    @@ -10,6 +10,90 @@
    + *   - #date_time_callbacks: An array of optional callbacks for the time
    

    See notes on date_date_callbacks above.

16. +++ b/core/lib/Drupal/Core/Entity/Element/EntityAutocomplete.php
    @@ -14,8 +14,24 @@
    + * The value returned by the element
    

    This looks like it was started but not completed?

17. +++ b/core/lib/Drupal/Core/Entity/Element/EntityAutocomplete.php
    @@ -14,8 +14,24 @@
    + * - #default_value:  An n entity object or an array of entity objects.
    

    stray "n"

18. +++ b/core/lib/Drupal/Core/Entity/Element/EntityAutocomplete.php
    @@ -14,8 +14,24 @@
    + * - #target_type: The entity type used in the autocomplete
    

    needs to end in .

19. +++ b/core/lib/Drupal/Core/Entity/Element/EntityAutocomplete.php
    @@ -14,8 +14,24 @@
    + * - #target_bundle: The bundle of the entity used in the control.
    

    what is a control?

20. +++ b/core/lib/Drupal/Core/Entity/Element/EntityAutocomplete.php
    @@ -14,8 +14,24 @@
    + * - #autocreate: Array defining defaults used by selections handlers for
    + *   entities that support automatic creation of entities such as taxonomy
    + *   terms.
    

    what is this trying to say? I don't understand it.

21. +++ b/core/lib/Drupal/Core/Render/Element/Ajax.php
    @@ -21,11 +21,11 @@ public function getInfo() {
    -    return array(
    +    return [
           '#header' => TRUE,
    -      '#commands' => array(),
    +      '#commands' => [],
           '#error' => NULL,
    -    );
    +    ];
    

    This change is good to make, but not on this issue. This issue is only supposed to be about making documentation for a set list of element types. Can we make a new issue to cover the [] array syntax in other element types?

22. +++ b/core/lib/Drupal/Core/Render/Element/Button.php
    @@ -20,10 +20,10 @@
    - * $form['actions']['preview'] = array(
    + * $form['actions']['preview'] = [
      *   '#type' => 'button',
      *   '#value' => $this->t('Preview'),
    - * );
    + * ];
    

    Same here... and for several others...

23. +++ b/core/lib/Drupal/Core/Render/Element/Form.php
    @@ -5,6 +5,16 @@
    + * Usage example:
    + * @code
    + * $form = [
    + *   '#method' => 'post',
    + * ];
    + * @endcode
    

    This example is confusing. Most of the others have a #type => 'form' line, but this doesn't. It needs to be explained. Or the line needs to be added.

24. +++ b/core/lib/Drupal/Core/Render/Element/ImageButton.php
    @@ -8,6 +8,17 @@
    + * - #src: Relative path to the image used in the button.
    

    Relative to what? And in the other issue, the usage example you had used "public://filename.png" -- is this also supported?

25. +++ b/core/lib/Drupal/Core/Render/Element/Item.php
    @@ -9,6 +9,21 @@
    + * - #markup: The data to be display.
    

    display -> displayed

26. +++ b/core/lib/Drupal/Core/Render/Element/Item.php
    @@ -9,6 +9,21 @@
    + * - #title: Title of the form element.
    

    Let's leave out the word "form" here.

27. +++ b/core/lib/Drupal/Core/Render/Element/LanguageSelect.php
    @@ -11,6 +11,16 @@
      * language_element_info_alter() to provide a proper language selector.
      *
    + * Usage Example:
    

    This element seems to be missing Properties section.

+++ b/core/lib/Drupal/Core/Render/Element/Date.php
@@ -13,11 +13,11 @@
- *   '#default_value' => array('year' => 2020, 'month' => 2, 'day' => 15,)
- * );
+ *   '#default_value' => ['year' => 2020, 'month' => 2, 'day' => 15]
+ * ];

This isn't actually valid. The Date element requires the default value to be a string in the format yyyy-mm-dd. And, FWIW this is also being addressed in this issue #2836530: Update Date element documentation for #date_date_format and usage for other date types such as time

This still needs to be done.

Updating summary.

Converted the MR. Then moved common date propertied to DateElementBase and moved the properties descriptions for methods in Dateitme and Datelist to the class documentation.

Shouldn't this be broken up some?

Appears to need a rebase

I've rebased and added some least essential comments in the MR.