Problem/Motivation
The class documentation on Drupal\Core\Render\Element\Date is incomplete, both for documenting properties and functionality. The Date element is used to create both <input type=date> and <input type=time> HTML elements. Other properties, eg ['#attributes']['type'] and ['#date_date_format'], are not documented at the top level. This hinders both people reading the code, and people consulting api.drupal.org for how to use this element.
Proposed resolution
Decide how much non-Drupal specific information to include (eg, document the min and max attributes), and what to refer to for more information (W3C spec? MDN?).
Update the documentation to be thorough, yet concise, based on the existing functionality.
Remaining tasks
Do we need to also mention type=datetime and type=datetime-local?
User interface changes
N/A
API changes
N/A
Data model changes
N/A
Original Report
The documentation for the Date render element is not valid. #default_value should be provided as a Y-m-d string instead of a keyed array as the documentation says.
Currently is says:
/**
* Provides a form element for date selection.
*
* Properties:
* - #default_value: An array with the keys: 'year', 'month', and 'day'.
* Defaults to the current date if no value is supplied.
*
* @code
* $form['expiration'] = array(
* '#type' => 'date',
* '#title' => $this->t('Content expiration'),
* '#default_value' => array('year' => 2020, 'month' => 2, 'day' => 15,)
* );
* @endcode
*
* @FormElement("date")
*/
which should be
/**
* Provides a form element for date selection.
*
* Properties:
* - #default_value: A string representing the date formatted as Y-m-d.
* Defaults to the current date if no value is supplied.
*
* @code
* $form['expiration'] = array(
* '#type' => 'date',
* '#title' => $this->t('Content expiration'),
* '#default_value' => '2020-02-15',
* );
* @endcode
*
* @FormElement("date")
*/
The default_value documentation could be improved. In the attached patch I've used "A string formatted as Y-m-d". But for someone not familiar with php date this might not be sufficient?