Correct some broken comment references (#9057)

srawlins · web-flow · commit 3b3a1ccfa1b3 · 2025-03-24T11:03:50.000-07:00
diff --git a/packages/devtools_app/lib/src/screens/performance/panes/flutter_frames/flutter_frame_model.dart b/packages/devtools_app/lib/src/screens/performance/panes/flutter_frames/flutter_frame_model.dart
@@ -12,8 +12,8 @@ import '../frame_analysis/frame_analysis_model.dart';
 /// Data describing a single Flutter frame.
 ///
 /// Each [FlutterFrame] should have 2 distinct pieces of data:
-/// * [uiEventFlow] : flow of events showing the UI work for the frame.
-/// * [rasterEventFlow] : flow of events showing the Raster work for the frame.
+/// * `uiEventFlow` : flow of events showing the UI work for the frame.
+/// * `rasterEventFlow` : flow of events showing the Raster work for the frame.
 class FlutterFrame {
   FlutterFrame._({
     required this.id,
diff --git a/packages/devtools_app/lib/src/shared/charts/treemap.dart b/packages/devtools_app/lib/src/shared/charts/treemap.dart
@@ -502,8 +502,8 @@ class _TreemapState extends State<Treemap> {
     );
   }
 
-  /// Checks if the touch point of the given [details] is overlapping with
-  /// a cell in [positionedCells].
+  /// Checks if the touch point of the given [event] is overlapping with a cell
+  /// in [positionedCells].
   ///
   /// If so, saves the matching hoveredNode.
   void _onHover(PointerHoverEvent event, List<PositionedCell> positionedCells) {
diff --git a/packages/devtools_app/lib/src/shared/config_specific/copy_to_clipboard/copy_to_clipboard.dart b/packages/devtools_app/lib/src/shared/config_specific/copy_to_clipboard/copy_to_clipboard.dart
@@ -12,9 +12,9 @@ import '_copy_to_clipboard_desktop.dart'
 
 final _log = Logger('copy_to_clipboard');
 
-/// Attempts to copy a String of `data` to the clipboard.
+/// Attempts to copy a String of [data] to the clipboard.
 ///
-/// Shows a [successMessage] [Notification] on the passed in `context`, if the
+/// Shows a [successMessage] Notification on the passed in `context`, if the
 /// copy is successfully done using the [Clipboard.setData] api. Otherwise it
 /// attempts to post the [data] to the parent frame where the parent frame will
 /// try to complete the copy (this fallback will only work in VSCode). When
diff --git a/packages/devtools_app/lib/src/shared/config_specific/drag_and_drop/drag_and_drop.dart b/packages/devtools_app/lib/src/shared/config_specific/drag_and_drop/drag_and_drop.dart
@@ -30,8 +30,9 @@ abstract class DragAndDropManager {
 
   /// The method is abstract, because we want to force descendants to define it.
   ///
-  /// The method is called in [impl], so any initialization the subclasses need,
-  /// like initializing listeners, should happen ahead of time in this method.
+  /// The method is called in [DragAndDropManager.impl], so any initialization
+  /// the subclasses need, like initializing listeners, should happen ahead of
+  /// time in this method.
   void init();
 
   @mustCallSuper
diff --git a/packages/devtools_app/lib/src/shared/console/primitives/scope.dart b/packages/devtools_app/lib/src/shared/console/primitives/scope.dart
@@ -28,7 +28,6 @@ class EvalScope {
   /// Refreshes variables in scope in response to failed eval.
   ///
   /// Returns true, if eval should retry.
-  /// Sets [refreshScopeChangeMessage] if scope changed.
   Future<bool> refreshRefs(String isolateId) async {
     removedVariables.clear();
     final isolateItems = _refs[isolateId] ?? {};
diff --git a/packages/devtools_app/lib/src/shared/console/widgets/description.dart b/packages/devtools_app/lib/src/shared/console/widgets/description.dart
@@ -2,6 +2,9 @@
 // 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 '../../../screens/inspector/inspector_tree_controller.dart';
+library;
+
 import 'package:devtools_app_shared/ui.dart';
 import 'package:flutter/material.dart';
 
diff --git a/packages/devtools_app/lib/src/shared/diagnostics/dart_object_node.dart b/packages/devtools_app/lib/src/shared/diagnostics/dart_object_node.dart
@@ -2,6 +2,9 @@
 // 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 '../console/widgets/expandable_variable.dart';
+library;
+
 import 'dart:async';
 
 import 'package:devtools_app_shared/utils.dart';
diff --git a/packages/devtools_app/lib/src/shared/diagnostics/diagnostics_node.dart b/packages/devtools_app/lib/src/shared/diagnostics/diagnostics_node.dart
@@ -2,6 +2,9 @@
 // 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 '../console/widgets/description.dart';
+library;
+
 import 'dart:async';
 
 import 'package:collection/collection.dart';
@@ -17,23 +20,19 @@ import 'object_group_api.dart';
 import 'primitives/instance_ref.dart';
 import 'primitives/source_location.dart';
 
-/// Defines diagnostics data for a [value].
+/// Defines diagnostics data for a value.
 ///
 /// [RemoteDiagnosticsNode] provides a high quality multi-line string dump via
-/// [toStringDeep]. The core members are the [name], [toDescription],
-/// [getProperties], [value], and [getChildren]. All other members exist
-/// typically to provide hints for how [toStringDeep] and debugging tools should
-/// format output.
+/// [toStringDeep].
 ///
 /// See also:
 ///
-/// * DiagnosticsNode class defined at https://github.com/flutter/flutter/blob/master/packages/flutter/lib/src/foundation/diagnostics.dart
-/// The difference is the class hierarchy is collapsed here as in
-/// package:flutter the subclasses exist more to simplify creation
-/// of Diagnostics than because the class hierarchy of Diagnostics is
-/// important. If you need to determine the exact Diagnostic class on the
-/// Dart side you can use the value of type. The raw Dart object value is
-/// also available via the getValue() method.
+/// * [DiagnosticsNode] - The difference is the class hierarchy is collapsed
+///   here as in package:flutter the subclasses exist more to simplify creation
+///   of Diagnostics than because the class hierarchy of Diagnostics is
+///   important. If you need to determine the exact Diagnostic class on the Dart
+///   side you can use the value of type. The raw Dart object value is also
+///   available via the `getValue()` method.
 class RemoteDiagnosticsNode extends DiagnosticableTree {
   RemoteDiagnosticsNode(
     this.json,
@@ -262,7 +261,7 @@ class RemoteDiagnosticsNode extends DiagnosticableTree {
 
   bool get hasIsQuoted => json.containsKey('quoted');
 
-  /// Optional unit the [value] is measured in.
+  /// Optional unit the [json] is measured in.
   ///
   /// Unit must be acceptable to display immediately after a number with no
   /// spaces. For example: 'physical pixels per logical pixel' should be a
@@ -273,16 +272,16 @@ class RemoteDiagnosticsNode extends DiagnosticableTree {
 
   bool get hasUnit => json.containsKey('unit');
 
-  /// String describing just the numeric [value] without a unit suffix.
+  /// String describing just the numeric [json] without a unit suffix.
   ///
   /// Only specified for Number properties.
   String? get numberToString => getStringMember('numberToString');
 
   bool get hasNumberToString => json.containsKey('numberToString');
 
-  /// Description to use if the property [value] is true.
+  /// Description to use if the property [json] is true.
   ///
-  /// If not specified and [value] equals true the property's priority [level]
+  /// If not specified and [json] equals true the property's priority [level]
   /// will be [DiagnosticLevel.hidden].
   ///
   /// Only applies to Flag properties.
@@ -292,7 +291,7 @@ class RemoteDiagnosticsNode extends DiagnosticableTree {
 
   /// Description to use if the property value is false.
   ///
-  /// If not specified and [value] equals false, the property's priority [level]
+  /// If not specified and [json] equals false, the property's priority [level]
   /// will be [DiagnosticLevel.hidden].
   ///
   /// Only applies to Flag properties.
@@ -315,8 +314,8 @@ class RemoteDiagnosticsNode extends DiagnosticableTree {
 
   /// Whether each of the values is itself a primitive value.
   ///
-  /// For example, bool|num|string are primitive values. This is useful as for
-  /// non-primitive values, the user may want to view the value with an
+  /// For example, `bool`|`num`|`string` are primitive values. This is useful as
+  /// for non-primitive values, the user may want to view the value with an
   /// interactive object debugger view to get more information on what the value
   /// is.
   List<bool>? get primitiveValues {
@@ -329,18 +328,18 @@ class RemoteDiagnosticsNode extends DiagnosticableTree {
 
   bool get hasValues => json.containsKey('values');
 
-  /// Description to use if the property [value] is not null.
+  /// Description to use if the property [json] is not `null`.
   ///
-  /// If the property [value] is not null and [ifPresent] is null, the
-  /// [level] for the property is [DiagnosticsLevel.hidden] and the description
-  /// from superclass is used.
+  /// If the property [json] is not `null` and [ifPresent] is `null`, the
+  /// [level] [level] for the property is [DiagnosticLevel.hidden] and the
+  /// description from superclass is used.
   ///
-  /// Only specified for ObjectFlagProperty.
+  /// Only specified for [ObjectFlagProperty].
   String? get ifPresent => getStringMember('ifPresent');
 
   bool get hasIfPresent => json.containsKey('ifPresent');
 
-  /// If the [value] of the property equals [defaultValue] the priority [level]
+  /// If the [json] of the property equals [defaultValue] the priority [level]
   /// of the property is downgraded to [DiagnosticLevel.fine] as the property
   /// value is uninteresting.
   ///
@@ -363,7 +362,7 @@ class RemoteDiagnosticsNode extends DiagnosticableTree {
   /// ifEmpty.
   String? get ifEmpty => getStringMember('ifEmpty');
 
-  /// Description if the property [value] is null.
+  /// Description if the property [json] is `null`.
   String? get ifNull => getStringMember('ifNull');
 
   bool get allowWrap => getBooleanMember('allowWrap', true);
@@ -378,12 +377,12 @@ class RemoteDiagnosticsNode extends DiagnosticableTree {
 
   bool get hasTooltip => json.containsKey('tooltip');
 
-  /// Whether a [value] of null causes the property to have [level]
-  /// [DiagnosticLevel.warning] warning that the property is missing a [value].
+  /// Whether a [json] of null causes the property to have [level]
+  /// [DiagnosticLevel.warning] warning that the property is missing a [json].
   bool get missingIfNull => getBooleanMember('missingIfNull', false);
 
   /// String representation of exception thrown if accessing the property
-  /// [value] threw an exception.
+  /// [json] threw an exception.
   String? get exception => getStringMember('exception');
 
   /// Whether accessing the property throws an exception.
@@ -416,11 +415,11 @@ class RemoteDiagnosticsNode extends DiagnosticableTree {
     return _creationLocation;
   }
 
-  /// String representation of the type of the property [value].
+  /// String representation of the type of the property [json].
   ///
   /// This is determined from the type argument `T` used to instantiate the
   /// [DiagnosticsProperty] class. This means that the type is available even if
-  /// [value] is null, but it also means that the [propertyType] is only as
+  /// [json] is null, but it also means that the [propertyType] is only as
   /// accurate as the type provided when invoking the constructor.
   ///
   /// Generally, this is only useful for diagnostic tools that should display
@@ -429,11 +428,9 @@ class RemoteDiagnosticsNode extends DiagnosticableTree {
   /// the word "null".
   String? get propertyType => getStringMember('propertyType');
 
-  /// If the [value] of the property equals [defaultValue] the priority [level]
+  /// If the [json] of the property equals [defaultValue] the priority [level]
   /// of the property is downgraded to [DiagnosticLevel.fine] as the property
   /// value is uninteresting.
-  ///
-  /// [defaultValue] has type [T] or is [kNoDefaultValue].
   DiagnosticLevel get defaultLevel {
     return getLevelMember('defaultLevel', DiagnosticLevel.info);
   }
diff --git a/packages/devtools_app/lib/src/shared/offline/offline_data.dart b/packages/devtools_app/lib/src/shared/offline/offline_data.dart
@@ -2,6 +2,9 @@
 // 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 '../framework/screen.dart';
+library;
+
 import 'dart:async';
 
 import 'package:devtools_app_shared/service.dart';
diff --git a/packages/devtools_app/lib/src/shared/primitives/utils.dart b/packages/devtools_app/lib/src/shared/primitives/utils.dart
@@ -561,11 +561,11 @@ double safeDivide(
 /// Unlike [ChangeNotifier], [Reporter] stores listeners in a set.  This allows
 /// O(1) addition/removal of listeners and O(N) listener dispatch.
 ///
-/// For small N (~ <20), [ChangeNotifier] implementations can be faster because
+/// For small N (~ &lt;20), [ChangeNotifier] implementations can be faster because
 /// array access is more efficient than set access. Use [Reporter] instead in
 /// cases where N is larger.
 ///
-/// When disposing, any object with a registered listener should [unregister]
+/// When disposing, any object with a registered listener should `unregister`
 /// itself.
 ///
 /// Only the object that created this reporter should call [notify].
diff --git a/packages/devtools_app/lib/src/shared/server/_survey_api.dart b/packages/devtools_app/lib/src/shared/server/_survey_api.dart
@@ -9,7 +9,7 @@ part of 'server.dart';
 /// The value is stored in the file '~/.flutter-devtools/.devtools'.
 ///
 /// This method must be called before calling other survey related methods
-/// ([isSurveyActionTaken], [setSurveyActionTaken], [surveyShownCount],
+/// ([surveyActionTaken], [setSurveyActionTaken], [surveyShownCount],
 /// [incrementSurveyShownCount]). If the active survey is not set, warnings are
 /// logged.
 Future<bool> setActiveSurvey(String value) async {
diff --git a/packages/devtools_app/lib/src/shared/table/_flat_table.dart b/packages/devtools_app/lib/src/shared/table/_flat_table.dart
@@ -6,11 +6,11 @@ part of 'table.dart';
 
 /// A [FlatTable] widget that is searchable.
 ///
-/// The table requires a [searchController], which is responsible for feeding
+/// The table requires a [SearchController], which is responsible for feeding
 /// information about search matches and the active search match to the table.
 ///
 /// This table will automatically refresh search matches on the
-/// [searchController] after sort operations that are triggered from the table.
+/// [SearchController] after sort operations that are triggered from the table.
 class SearchableFlatTable<T extends SearchableDataMixin> extends FlatTable<T> {
   SearchableFlatTable({
     super.key,
@@ -136,8 +136,8 @@ class FlatTable<T> extends StatefulWidget {
   /// and scroll position for this table (when [preserveVerticalScrollPosition]
   /// is true).
   ///
-  /// We use [TableUiStateStore] to store [_TableUiState] by this key so that
-  /// we can save and restore this state without having to keep [State] or table
+  /// We use [TableUiStateStore] to store [TableUiState] by this key so that we
+  /// can save and restore this state without having to keep [State] or table
   /// controller objects alive.
   final String dataKey;
 
diff --git a/packages/devtools_app/lib/src/shared/table/_tree_table.dart b/packages/devtools_app/lib/src/shared/table/_tree_table.dart
@@ -59,8 +59,8 @@ class TreeTable<T extends TreeNode<T>> extends StatefulWidget {
   /// and scroll position for this table (when [preserveVerticalScrollPosition]
   /// is true).
   ///
-  /// We use [TableUiStateStore] to store [_TableUiState] by this key so that
-  /// we can save and restore this state without having to keep [State] or table
+  /// We use [TableUiStateStore] to store [TableUiState] by this key so that we
+  /// can save and restore this state without having to keep [State] or table
   /// controller objects alive.
   final String dataKey;
 
diff --git a/packages/devtools_app/lib/src/shared/table/column_widths.dart b/packages/devtools_app/lib/src/shared/table/column_widths.dart
@@ -2,6 +2,9 @@
 // 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:math';
 
 import 'package:devtools_app_shared/ui.dart';
@@ -24,7 +27,7 @@ final defaultVariableWidthColumnSize = scaleByFontFactor(1200.0);
 
 extension FlatColumnWidthExtension<T> on FlatTableController<T> {
   /// Calculates [FlatTable] column widths when the columns should be sized as
-  /// either 1) the [fixedWidthPx] specified by the column, or
+  /// either 1) the `fixedWidthPx` specified by the column, or
   /// 2) [defaultVariableWidthColumnSize], the minimum width that can be used
   /// for variable width columns.
   ///
@@ -135,7 +138,7 @@ extension TreeColumnWidthExtension<T extends TreeNode<T>>
     on TreeTableController<T> {
   /// Calculates [TreeTable] column widths.
   ///
-  /// Non-tree columns will be sized with their specified [fixedWidthPx]. The
+  /// Non-tree columns will be sized with their specified `fixedWidthPx`. The
   /// tree column width will include space for the max indentation of the fully
   /// expanded tree and [defaultVariableWidthColumnSize] for displaying the
   /// tree column content.
