Issue #2656578 by felribeiro, malavya: Tableselect documentation around #header needs more detail

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

@@ -16,13 +16,40 @@
  * Provides a form element for a table with radios or checkboxes in left column.
  *
  * Properties:
- * - #header: Table headers used in the table.
+ * - #header: An array of table header labels.
  * - #options: An associative array where each key is the value returned when
  *   a user selects the radio button or checkbox, and each value is the row of
  *   table data.
+ * - #empty: The message to display if table does not have any options.
+ * - #multiple: Set to FALSE to render the table with radios instead checkboxes.
+ * - #js_select: Set to FALSE if you don't want the select all checkbox added to
+ *   the header.
+ *
+ * Other properties of the \Drupal\Core\Render\Element\Table element are also
+ * available.
  *
  * Usage example:
- * See https://www.drupal.org/node/945102 for an example and full explanation.
+ * @code
+ * $header = [
+ *   'first_name' => t('First Name'),
+ *   'last_name' => t('Last Name'),
+ * ];
+ *
+ * $options = [
+ *   1 => ['first_name' => 'Indy', 'last_name' => 'Jones'],
+ *   2 => ['first_name' => 'Darth', 'last_name' => 'Vader'],
+ *   3 => ['first_name' => 'Super', 'last_name' => 'Man'],
+ * ];
+ *
+ * $form['table'] = array(
+ *   '#type' => 'tableselect',
+ *   '#header' => $header,
+ *   '#options' => $options,
+ *   '#empty' => t('No users found'),
+ * );
+ * @endcode
+ *
+ * See https://www.drupal.org/node/945102 for a full explanation.
  *
  * @see \Drupal\Core\Render\Element\Table
  *