Update DataTable documentation (#151356)

This PR resolves [some problems I was having with `DataTable`](#151005), based on advice from the style guide: > ### Answer your own questions straight away > If you find yourself asking a question about our systems, please place whatever answer you subsequently discover into the documentation in the same place where you first looked for the answer. That way, the documentation will consist of answers to real questions, where people would look to find them. The `DataTable` documentation now specifies that the widget is based on the Material 2 spec, and it offers a list of useful alternatives. <br> Additionally, an item in the "See also" section was updated to use a reliable Go link: ```diff - /// * <https://material.io/design/components/data-tables.html> /// * <https://material.io/go/design-data-tables> ```
flutter · Jul 8, 2024 · a3c7094 · a3c7094
1 parent e1a6f76
commit a3c7094
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 18 deletions.
diff --git a/packages/flutter/lib/src/material/data_table.dart b/packages/flutter/lib/src/material/data_table.dart
@@ -349,27 349,29 @@ class DataCell {
  onTapCancel != null;
 }
 
-/// A Material Design data table.
 /// A data table that follows the
 /// [Material 2](https://material.io/go/design-data-tables)
 /// design specification.
 ///
 /// {@youtube 560 315 https://www.youtube.com/watch?v=ktTajqbhIcY}
 ///
-/// Displaying data in a table is expensive, because to lay out the
-/// table all the data must be measured twice, once to negotiate the
-/// dimensions to use for each column, and once to actually lay out
-/// the table given the results of the negotiation.
 /// ## Performance considerations
 ///
-/// For this reason, if you have a lot of data (say, more than a dozen
-/// rows with a dozen columns, though the precise limits depend on the
-/// target device), it is suggested that you use a
-/// [PaginatedDataTable] which automatically splits the data into
-/// multiple pages.
 /// Columns are sized automatically based on the table's contents.
 /// It's expensive to display large amounts of data with this widget,
 /// since it must be measured twice: once to negotiate each column's
 /// dimensions, and again when the table is laid out.
 ///
-/// ## Performance considerations when wrapping [DataTable] with [SingleChildScrollView]
 /// A [SingleChildScrollView] mounts and paints the entire child, even
 /// when only some of it is visible. For a table that effectively handles
 /// large amounts of data, here are some other options to consider:
 ///
-/// Wrapping a [DataTable] with [SingleChildScrollView] is expensive as [SingleChildScrollView]
-/// mounts and paints the entire [DataTable] even when only some rows are visible. If scrolling in
-/// one direction is necessary, then consider using a [CustomScrollView], otherwise use [PaginatedDataTable]
-/// to split the data into smaller pages.
 /// * `TableView`, a widget from the
 /// [two_dimensional_scrollables](https://pub.dev/packages/two_dimensional_scrollables)
 /// package.
 /// * [PaginatedDataTable], which automatically splits the data into
 /// multiple pages.
 /// * [CustomScrollView], for greater control over scrolling effects.
 ///
 /// {@tool dartpad}
 /// This sample shows how to display a [DataTable] with three columns: name, age, and
@@ -402,7 404,10 @@ class DataCell {
 /// * [DataCell], which contains the data for a single cell in the data table.
 /// * [PaginatedDataTable], which shows part of the data in a data table and
 /// provides controls for paging through the remainder of the data.
-/// * <https://material.io/design/components/data-tables.html>
 /// * `TableView` from the
 /// [two_dimensional_scrollables](https://pub.dev/packages/two_dimensional_scrollables)
 /// package, for displaying large amounts of data without pagination.
 /// * <https://material.io/go/design-data-tables>
 class DataTable extends StatelessWidget {
  /// Creates a widget describing a data table.
  ///

diff --git a/packages/flutter/lib/src/material/paginated_data_table.dart b/packages/flutter/lib/src/material/paginated_data_table.dart
@@ -21,7 21,9 @@ import 'material_state.dart';
 import 'progress_indicator.dart';
 import 'theme.dart';
 
-/// A Material Design data table that shows data using multiple pages.
 /// A table that follows the
 /// [Material 2](https://material.io/go/design-data-tables)
 /// design specification, using multiple pages to display data.
 ///
 /// A paginated data table shows [rowsPerPage] rows of data per page and
 /// provides controls for showing other pages.
@@ -52,7 54,10 @@ import 'theme.dart';
 /// See also:
 ///
 /// * [DataTable], which is not paginated.
-/// * <https://material.io/go/design-data-tables#data-tables-tables-within-cards>
 /// * `TableView` from the
 /// [two_dimensional_scrollables](https://pub.dev/packages/two_dimensional_scrollables)
 /// package, for displaying large amounts of data without pagination.
 /// * <https://material.io/go/design-data-tables>
 class PaginatedDataTable extends StatefulWidget {
  /// Creates a widget describing a paginated [DataTable] on a [Card].
  ///