#rows property should clarify how simple vs. complex is determined

API pages:
https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Render%21...
https://api.drupal.org/api/drupal/core%21includes%21theme.inc/function/t...

Problem:

The documentation on the #row property does not describe what determines whether an array is parsed as a simple "array of cell contents" or the more complex "array of properties as described in table.html.twig". This can lead to confusion.

The logic that determines whether #row is simple or complex appears to take place in template_preprocess_table()

        // Check if we're dealing with a simple or complex row
        if (isset($row['data'])) {
          $cells = $row['data'];
          $variables['no_striping'] = $row['no_striping'] ?? FALSE;

          // Set the attributes array and exclude 'data' and 'no_striping'.
          $row_attributes = $row;
          unset($row_attributes['data']);
          unset($row_attributes['no_striping']);
        }

This means that 'data' is a special/reserved key name that should be called out in the documentation. If you have been successfully using the simple "array of cell contents" approach with an associative array for #row, and then you add a new table column under the array key 'data', it will unexpectedly fail with a cryptic message:

Warning: foreach() argument must be of type array|object, string given in template_preprocess_table() (line 1034 of core/includes/theme.inc).
template_preprocess_table(Array, 'table', Array)

Furthermore, since the Table form element starts out like most Form API components with hash (#) prefixes to identify special properties in the render array, it's confusing to switch to not using the prefix for special properties in a sub-component of the form element. (You'd expect to use '#data' not 'data'.) It would be helpful to call out/clarify this shift when pointing to table.html.twig in the documentation.

The single example currently on the page appears to be of the third, most complex approach, "Alternatively specify the data for the table as child elements of the table element," but because it's not identified as such, it's difficult for someone new to Form API tables to figure that out. It would be really helpful to add specific examples of the three different row types, clearly labeled, and in the order presented in the properties documentation section.

Alternately, the logic in template_preprocess_table() could be expanded to check whether $row['data'] contains data that can be properly parsed as the more complex row type (where 'data' itself contains an array of elements that can be iterated through and rendered as cells), and if not, fall back to the simple row type (where 'data' is just one of many column keys).