Resolve all remaining broken comment references (#9074)

Author: srawlins

analysis_options.yaml

@@ -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

packages/devtools_app/lib/src/extensions/extension_service.dart

@@ -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;
 

packages/devtools_app/lib/src/shared/analytics/_analytics_web.dart

@@ -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,

packages/devtools_app/lib/src/shared/config_specific/drag_and_drop/drag_and_drop.dart

@@ -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.

packages/devtools_app/lib/src/shared/offline/offline_data.dart

@@ -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].

packages/devtools_app/lib/src/shared/primitives/graph.dart

@@ -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

packages/devtools_app/lib/src/shared/table/table.dart

@@ -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.
   ///

packages/devtools_app/lib/src/shared/table/table_controller.dart

@@ -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;
 

packages/devtools_app/lib/src/shared/table/table_data.dart

@@ -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

packages/devtools_app/lib/src/shared/ui/common_widgets.dart

@@ -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.