flutter · srawlins · Mar 27, 2025 · Mar 27, 2025
@@ -67,7 +67,7 @@ linter:
     - cancel_subscriptions
     # - cascade_invocations # not yet tested
     # - close_sinks # https://github.com/flutter/flutter/issues/5789
-    # - comment_references # blocked on https://github.com/dart-lang/dartdoc/issues/1153
+    - comment_references
     # - constant_identifier_names # https://github.com/dart-lang/linter/issues/204
     - control_flow_in_finally
     - directives_ordering

@@ -20,17 +20,16 @@ final _log = Logger('ExtensionService');
 /// visible extensions.
 typedef DevToolsExtensionsGroup =
     ({
-      /// All the DevTools extensions, runtime and static, that are available for
-      /// the connected application, regardless of whether they have been enabled or
-      /// disabled by the user.
-      ///
-      /// This set of extensions will include one version of a DevTools extension
-      /// per package and will exclude any duplicates that have been marked as
-      /// ignored in [_maybeIgnoreExtensions].
+      // All the DevTools extensions, runtime and static, that are available for
+      // the connected application, regardless of whether they have been enabled
+      // or disabled by the user.
+      //
+      // This set of extensions will include one version of a DevTools extension
+      // per package.
       List<DevToolsExtensionConfig> availableExtensions,
 
-      /// DevTools extensions that are visible in their own DevTools screen (i.e.
-      /// extensions that have not been manually disabled by the user).
+      // DevTools extensions that are visible in their own DevTools screen (i.e.
+      // extensions that have not been manually disabled by the user).
       List<DevToolsExtensionConfig> visibleExtensions,
     });
 
@@ -71,8 +70,7 @@ class ExtensionService extends DisposableController
   /// disabled by the user.
   ///
   /// This set of extensions will include one version of a DevTools extension
-  /// per package and will exclude any duplicates that have been marked as
-  /// ignored in [_maybeIgnoreExtensions].
+  /// per package.
   List<DevToolsExtensionConfig> get availableExtensions =>
       _currentExtensions.value.availableExtensions;
 

@@ -676,9 +676,7 @@ String? _lastGaError;
 /// Reports an error to analytics.
 ///
 /// [errorMessage] is the description of the error.
-/// [stackTraceSubstrings] is the stack trace broken up into substrings of
-/// size [ga4ParamValueCharacterLimit] so that we can send the stack trace in
-/// chunks to GA4 through unified_analytics.
+/// [stackTrace] is the stack trace.
 void reportError(
   String errorMessage, {
   stack_trace.Trace? stackTrace,

@@ -191,8 +191,7 @@ class DragAndDropState extends State<DragAndDrop> {
   }
 }
 
-/// MetaData for widgets related to drag and drop functionality ([DragAndDrop],
-/// [DragAndDropEventAbsorber]).
+/// MetaData for widgets related to drag and drop functionality ([DragAndDrop]).
 ///
 /// Drag and drop widgets will contain a [MetaData] widget with the `metaData`
 /// field set to an instance of this class.

@@ -41,9 +41,9 @@ class OfflineDataController {
   /// Stores the [ConnectedApp] instance temporarily while switching between
   /// offline and online modes.
   ///
-  /// We store this because the [serviceManager] is a global manager and expects
-  /// only one connected app. So we swap out the online connected app with the
-  /// offline app data while in offline mode.
+  /// We store this because the `serviceConnection.serviceManager` is a global
+  /// manager and expects only one connected app. So we swap out the online
+  /// connected app with the offline app data while in offline mode.
   ConnectedApp? previousConnectedApp;
 
   /// Whether DevTools should load offline data for [screenId].

@@ -26,26 +26,30 @@ class GraphNode {
   /// outgoing edges going to `this` node.
   ///
   /// For example:
+  /// ```none
   ///        A (predecessor node)
   ///      /  \
   ///     |    |
   ///      \  /
   ///       B (this node)
   ///
   /// ==> successorEdgeCounts[A] = 2
+  /// ```
   final predecessorEdgeCounts = <GraphNode, int>{};
 
   /// Maps successor [GraphNode]s from [successors] to the number of incoming
   /// edges coming from `this` node.
   ///
   /// For example:
+  /// ```none
   ///        A (this node)
   ///      /  \
   ///     |    |
   ///      \  /
   ///       B (successor node)
   ///
   /// ==> successorEdgeCounts[B] = 2
+  /// ```
   final successorEdgeCounts = <GraphNode, int>{};
 
   /// Returns the percentage of this node's predecessor edges that connect to

@@ -119,7 +119,7 @@ class DevToolsTableState<T> extends State<DevToolsTable<T>>
 
   late List<T> _data;
 
-  /// An adjusted copy of [widget.columnWidths] where any variable width columns
+  /// An adjusted copy of `widget.columnWidths` where any variable width columns
   /// may be increased so that the sum of all column widths equals the available
   /// screen space.
   ///

@@ -1,6 +1,10 @@
 // Copyright 2025 The Flutter Authors
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file or at https://developers.google.com/open-source/licenses/bsd.
+
+/// @docImport 'table.dart';
+library;
+
 import 'dart:collection';
 import 'dart:math';
 
@@ -56,13 +60,13 @@ class FlatTableController<T> extends TableControllerBase<T> {
   /// Callback that will be called after each table sort operation.
   final VoidCallback? onDataSorted;
 
-  /// The unmodified, original data for the active data set [_tableData.value].
+  /// The unmodified, original data for the active data set `_tableData.value`.
   ///
   /// This is reset each time [setData] is called, when [sortOriginalData] is
   /// false.
   late UnmodifiableListView<T> _unmodifiableOriginalData;
 
-  /// The modifiable, original data for the active data set [_tableData.value].
+  /// The modifiable, original data for the active data set `_tableData.value`.
   ///
   /// This is reset each time [setData] is called, when [sortOriginalData] is
   /// true.
@@ -255,16 +259,16 @@ abstract class TableControllerBase<T> extends DisposableController {
   /// dividing lines will be drawn for each column group boundary.
   final bool includeColumnGroupHeaders;
 
-  /// The default sort column for tables using this [TableController].
+  /// The default sort column for tables using this TableController.
   ///
   /// The currently active sort column will be stored as part of the
-  /// [TableUiState] for the current data (stored in [_tableUiStateByData]).
+  /// [TableUiState] for the current data.
   final ColumnData<T> defaultSortColumn;
 
-  /// The default [SortDirection] for tables using this [TableController].
+  /// The default [SortDirection] for tables using this TableController.
   ///
   /// The currently active [SortDirection] will be stored as part of the
-  /// [TableUiState] for the current data (stored in [_tableUiStateByData]).
+  /// [TableUiState] for the current data.
   final SortDirection defaultSortDirection;
 
   /// The column to be used by the table sorting algorithm to break a tie for
@@ -289,7 +293,7 @@ abstract class TableControllerBase<T> extends DisposableController {
   /// The key for the current table data.
   ///
   /// The value assigned to [TableData.key] will only be used if
-  /// [persistUiStates] has been set to true. Otherwise, all data sets will be
+  /// `persistUiStates` has been set to true. Otherwise, all data sets will be
   /// assigned to and looked up from the key [TableData.defaultDataKey].
   String get _currentDataKey => _tableData.value.key;
 

@@ -15,7 +15,7 @@ import '../primitives/utils.dart';
 /// not manage any stateful data. The table controllers expect columns to be
 /// solely responsible for declaring how to layout table data.
 ///
-/// Any data that can't be stored on the [dataObject] may be accessed by passing
+/// Any data that can't be stored on the `dataObject` may be accessed by passing
 /// a long-living controller to the constructor of the [ColumnData] subclass.
 ///
 /// The controller is expected to be alive for the duration of the app

@@ -1939,7 +1939,7 @@ class ElevatedCard extends StatelessWidget {
 /// [AutomaticKeepAliveClientMixin] on its [State].
 ///
 /// Wrap a widget in this class if you want [child] to stay alive, and avoid
-/// rebuilding. This is useful for children of [TabView]s. When wrapped in this
+/// rebuilding. This is useful for children of TabViews. When wrapped in this
 /// wrapper, [child] will not be destroyed and rebuilt when switching tabs.
 ///
 /// See [AutomaticKeepAliveClientMixin] for more information.

@@ -8,7 +8,7 @@ import 'package:flutter/material.dart';
 
 import '../analytics/analytics.dart' as ga;
 
-/// A [DropDownButton] implementation that reports selection changes to our
+/// A DropDownButton implementation that reports selection changes to our
 /// analytics.
 class AnalyticsDropDownButton<T> extends StatelessWidget {
   const AnalyticsDropDownButton({

@@ -27,9 +27,7 @@ typedef SettingFilters<T> = List<SettingFilter<T, Object>>;
 /// [createSettingFilters] and [createQueryFilterArgs].
 ///
 /// Classes mixing in [FilterControllerMixin] must also extend
-/// [DisposableController] and mixin [AutoDisposeControllerMixin], and a class
-/// can subscribe to updates to the active filter by calling
-/// [initFilterController].
+/// [DisposableController] and mixin [AutoDisposeControllerMixin].
 mixin FilterControllerMixin<T> on DisposableController
     implements AutoDisposeControllerMixin {
   final filteredData = ListValueNotifier<T>(<T>[]);

@@ -4,9 +4,8 @@
 
 /// Platform independent definition of icons.
 ///
-/// See [HtmlIconRenderer] for a browser specific implementation of icon
-/// rendering. If you add an Icon class you also need to add a renderer class
-/// to handle the actual platform specific icon rendering.
+/// If you add an Icon class you also need to add a renderer class to handle the
+/// actual platform specific icon rendering.
 /// The benefit of this approach is that icons can be const objects and tests
 /// of code that uses icons can run on the Dart VM.
 library;

@@ -31,8 +31,8 @@ final _log = Logger('packages/devtools_app/lib/src/shared/ui/search');
 
 /// Mixin that manages search logic.
 ///
-/// When mixing this mixin into a class, dispose() must be called as part of the
-/// class' lifecycle management.
+/// When mixing this mixin into a class, `dispose()` must be called as part of
+/// the class's lifecycle management.
 mixin SearchControllerMixin<T extends SearchableDataMixin>
     on DisposableController {
   final _searchNotifier = ValueNotifier<String>('');
@@ -214,7 +214,7 @@ mixin SearchControllerMixin<T extends SearchableDataMixin>
   /// Default search matching logic.
   ///
   /// The use of this method requires both [currentDataToSearchThrough] and
-  /// [T.matchesSearchToken] to be implemented.
+  /// [SearchableDataMixin.matchesSearchToken] to be implemented on [T].
   List<T> matchesForSearch(
     String search, {
     bool searchPreviousMatches = false,
@@ -855,17 +855,12 @@ class SearchTextEditingController extends TextEditingController {
 
 /// A stateful text field with search capability.
 ///
-/// [_SearchFieldState] automatically handles the lifecycle of the search field
-/// through the [SearchFieldMixin].
-///
 /// Use this widget for simple use cases where the elements initialized and
-/// disposed in [SearchControllerMixin.initSearch] and
-/// [SearchControllerMixin.disposeSearch] are not used outside of the context
-/// of the search code.
+/// disposed in [SearchControllerMixin.init] and [SearchControllerMixin.dispose]
+/// are not used outside of the context of the search code.
 ///
 /// If these elements need to be used by the widget state that builds the search
-/// field, consider using [StatelessSearchField] instead and manually mixing in
-/// [SearchFieldMixin] so that you can manage the lifecycle properly.
+/// field, consider using [StatelessSearchField] instead.
 class SearchField<T extends SearchControllerMixin> extends StatefulWidget {
   SearchField({
     required this.searchController,
@@ -936,14 +931,11 @@ class _SearchFieldState extends State<SearchField> with AutoDisposeMixin {
 
 /// A stateless text field with search capability.
 ///
-/// The widget that builds [StatelessSearchField] is responsible for mixing in
-/// [SearchFieldMixin], which manages the search field lifecycle.
-///
 /// Use this widget for use cases where the default state management that
 /// [SearchField] provides is not sufficient for the use case. This can be the
 /// case when the elements initialized and disposed in
-/// [SearchControllerMixin.initSearch] and [SearchControllerMixin.disposeSearch]
-/// need to be accessed outside of the context of the search code.
+/// [SearchControllerMixin.init] and [SearchControllerMixin.dispose] need to be
+/// accessed outside of the context of the search code.
 class StatelessSearchField<T extends SearchableDataMixin>
     extends StatelessWidget {
   const StatelessSearchField({
@@ -1096,9 +1088,6 @@ class StatelessSearchField<T extends SearchableDataMixin>
 }
 
 /// A text field with autocomplete search capability.
-///
-/// The widget that builds [AutoCompleteSearchField] is responsible for mixing
-/// in [SearchFieldMixin], which manages the search field lifecycle.
 class AutoCompleteSearchField extends StatefulWidget {
   const AutoCompleteSearchField({
     super.key,
@@ -1161,8 +1150,8 @@ class AutoCompleteSearchField extends StatefulWidget {
   /// autocomplete overlay is not showing.
   final bool clearFieldOnEscapeWhenOverlayHidden;
 
-  /// Handler called when either [controller.searchFieldFocusNode] or
-  /// [controller.autocompleteFocusNode] has lost focus.
+  /// Handler called when either `controller.searchFieldFocusNode` or
+  /// `controller.autocompleteFocusNode` has lost focus.
   final VoidCallback? onFocusLost;
 
   /// The maximum number of lines, by default one.
@@ -1456,7 +1445,7 @@ mixin SearchableDataMixin {
   bool isActiveSearchMatch = false;
 
   /// Whether this [SearchableDataMixin] is a match for the search query
-  /// [search].
+  /// [regExpSearch].
   ///
   /// This method is used by [SearchControllerMixin.matchesForSearch]. If
   /// [SearchControllerMixin.matchesForSearch] is overridden in such a way that

@@ -239,9 +239,9 @@ class ThemedColorPair {
 /// A theme-dependent color.
 ///
 /// When possible, themed colors should be specified in an extension on
-/// [ColorScheme] using the [ColorScheme.isLight] getter. However, this class
-/// may be used when access to the [BuildContext] is not available at the time
-/// the color needs to be specified.
+/// [ColorScheme] using the [DevToolsSharedColorScheme.isLight] getter. However,
+/// this class may be used when access to the [BuildContext] is not available at
+/// the time the color needs to be specified.
 class ThemedColor {
   const ThemedColor({required this.light, required this.dark});
 

@@ -266,12 +266,12 @@ class BottomUpTransformer<T extends ProfilableDataMixin<T>> {
     return bottomUpRoots;
   }
 
-  /// Cascades the [exclusiveSampleCount] and [inclusiveSampleCount] of [node]
+  /// Cascades the `exclusiveSampleCount` and `inclusiveSampleCount` of [node]
   /// to all of its children (recursive).
   ///
   /// This is necessary for the transformation of a [ProfilableDataMixin] to its
   /// bottom-up representation. This is an intermediate step between
-  /// [generateBottomUpRoots] and the [mergeSamples] callback passed to
+  /// [generateBottomUpRoots] and the `mergeSamples` callback passed to
   /// [bottomUpRootsFor].
   @visibleForTesting
   void cascadeSampleCounts(T node) {

@@ -47,7 +47,7 @@ void debugLogger(String message) {
 /// whether DevTools is using a light or dark theme.
 ///
 /// This utility method should be used in favor of checking
-/// [preferences.darkModeTheme.value] so that the embedded case is always
+/// `preferences.darkModeTheme.value` so that the embedded case is always
 /// handled properly.
 bool isDarkThemeEnabled() {
   return isEmbedded() && ideTheme.ideSpecifiedTheme
@@ -213,8 +213,7 @@ class Debouncer extends Disposable {
 
 typedef DebounceCancelledCallback = bool Function();
 
-/// A periodic debouncer that calls the given [callback] at most once per
-/// [duration].
+/// A periodic debouncer that calls a callback at most once in a given duration.
 class PeriodicDebouncer {
   /// Start running the periodic debouncer.
   ///
@@ -277,14 +276,15 @@ Future<void> launchUrlWithErrorHandling(String url) async {
   );
 }
 
-/// A worker that will run [callback] in groups of [chunkSize], when [doWork] is called.
+/// A worker that will run [callback] in groups of [_chunkSize], when [doWork]
+/// is called.
 ///
-/// [progressCallback] will be called with 0.0 progress when starting the work and any
-/// time a chunk finishes running, with a value that represents the proportion of
-/// indices that have been completed so far.
+/// [progressCallback] will be called with 0.0 progress when starting the work
+/// and any time a chunk finishes running, with a value that represents the
+/// proportion of indices that have been completed so far.
 ///
-/// This class may be helpful when sets of work need to be done over a list, while
-/// avoiding blocking the UI thread.
+/// This class may be helpful when sets of work need to be done over a list,
+/// while avoiding blocking the UI thread.
 class InterruptableChunkWorker {
   InterruptableChunkWorker({
     int chunkSize = _defaultChunkSize,