Correct some broken comment references (#8973)

Author: srawlins

packages/devtools_app/lib/src/app.dart

@@ -560,18 +560,14 @@ class DevToolsAppState extends State<DevToolsApp> with AutoDisposeMixin {
 /// screen's controller, if one exists, as well as enabling offline support.
 ///
 /// [C] corresponds to the type of the screen's controller, which is created by
-/// [createController] or provided by [controllerProvider].
+/// [createController].
 class DevToolsScreen<C extends DevToolsScreenController> {
   const DevToolsScreen(this.screen, {this.createController});
 
   final Screen screen;
 
   /// Responsible for creating the controller for this screen, if non-null.
   ///
-  /// The controller will then be provided via [controllerProvider], and
-  /// widgets depending on this controller can access it by calling
-  /// `Provider<C>.of(context)`.
-  ///
   /// If [createController] and `controller` are both null, [screen] will be
   /// responsible for creating and maintaining its own controller.
   ///

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

@@ -42,7 +42,7 @@ class ExtensionService extends DisposableController
   /// [ExtensionService] will manage DevTools extensions for.
   ///
   /// When null, [_appRoot] will be calculated from the
-  /// `serviceConnection.serviceManager`'s currently connected app. See [_initAppRoot].
+  /// `serviceConnection.serviceManager`'s currently connected app.
   final Uri? fixedAppRoot;
 
   /// Whether to ignore the VM service connection for the context of this

packages/devtools_app/lib/src/screens/debugger/codeview_controller.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 'codeview.dart';
+library;
+
 import 'dart:async';
 import 'dart:convert';
 

packages/devtools_app/lib/src/screens/network/network_controller.dart

@@ -549,9 +549,8 @@ class CurrentNetworkRequests extends ValueNotifier<List<NetworkRequest>> {
     notifyListeners();
   }
 
-  /// Update or add the [request] to the [requests] depending on whether or not
-  /// its [request.id] already exists in the list.
-  ///
+  /// Updates or adds the [requests] to the [_requestsById] depending on whether
+  /// or not its `id` already exists in the map.
   void _updateOrAddRequests(List<HttpProfileRequest> requests) {
     for (int i = 0; i < requests.length; i++) {
       final request = requests[i];

packages/devtools_app/lib/src/screens/performance/panes/controls/enhance_tracing/enhance_tracing.dart

@@ -82,7 +82,7 @@ extension TraceWidgetBuildsScopeExtension on TraceWidgetBuildsScope {
     }
   }
 
-  /// Returns the opposite [TraceWidgetBuildsScope] from [this].
+  /// Returns the opposite [TraceWidgetBuildsScope] from `this`.
   TraceWidgetBuildsScope get opposite {
     switch (this) {
       case TraceWidgetBuildsScope.all:
@@ -125,11 +125,11 @@ class _TraceWidgetBuildsSettingState extends State<TraceWidgetBuildsSetting>
   /// [TraceWidgetBuildsScope] or null if widget builds are not being traced.
   final _selectedScope = ValueNotifier<TraceWidgetBuildsScope?>(null);
 
-  /// Whether either of the extensions in [_traceWidgetBuildsExtensions.values]
+  /// Whether either of the extensions in `_traceWidgetBuildsExtensions.values`
   /// are enabled.
   final _tracingEnabled = ValueNotifier<bool>(false);
 
-  /// Whether either of the extensions in [_traceWidgetBuildsExtensions.values]
+  /// Whether either of the extensions in `_traceWidgetBuildsExtensions.values`
   /// are available.
   final _tracingAvailable = ValueNotifier<bool>(false);
 

packages/devtools_app/lib/src/screens/performance/panes/flutter_frames/flutter_frames_controller.dart

@@ -55,10 +55,10 @@ class FlutterFramesController extends PerformanceFeatureController {
   final _pendingFlutterFrames = <FlutterFrame>[];
 
   /// The collection of Flutter frames that have not yet been linked to their
-  /// respective [TimelineEvent]s for the UI and Raster thread.
+  /// respective [FlutterTimelineEvent]s for the UI and Raster thread.
   ///
   /// These [FlutterFrame]s are keyed by the Flutter frame ID that matches the
-  /// frame id in the corresponding [TimelineEvent]s.
+  /// frame id in the corresponding [FlutterTimelineEvent]s.
   final _unassignedFlutterFrames = <int, FlutterFrame>{};
 
   /// Tracks the current frame undergoing selection so that we can equality

packages/devtools_app/lib/src/screens/performance/panes/frame_analysis/frame_hints.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 '../flutter_frames/flutter_frame_model.dart';
+library;
+
 import 'package:devtools_app_shared/ui.dart';
 import 'package:devtools_app_shared/utils.dart';
 import 'package:flutter/material.dart';

packages/devtools_app/lib/src/screens/performance/panes/timeline_events/perfetto/_perfetto_controller_web.dart

@@ -2,6 +2,10 @@
 // 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 '../timeline_events_controller.dart';
+/// @docImport '../timeline_events_view.dart';
+library;
+
 import 'dart:async';
 import 'dart:ui_web' as ui_web;
 
@@ -29,15 +33,15 @@ const _debugUseLocalPerfetto = false;
 ///
 /// A new instance of [PerfettoController] will be created for each connected
 /// app and for each load of offline data. Each time [PerfettoController.init]
-/// is called, we create a new [html.IFrameElement] and register it to
-/// [PerfettoController.viewId] via
-/// [ui_web.platformViewRegistry.registerViewFactory]. Each new [html.IFrameElement]
-/// must have a unique id in the [PlatformViewRegistry], which
-/// [_viewIdIncrementer] is used to create.
+/// is called, we create a new [HTMLIFrameElement] and register it to
+/// `PerfettoController.viewId` via
+/// [ui_web.PlatformViewRegistry.registerViewFactory]. Each new
+/// [HTMLIFrameElement] must have a unique id in the
+/// [ui_web.PlatformViewRegistry], which [_viewIdIncrementer] is used to create.
 var _viewIdIncrementer = 0;
 
 /// Events that are passed between DevTools and the embedded Perfetto iFrame via
-/// [window.postMessage].
+/// [Window.postMessage].
 enum EmbeddedPerfettoEvent {
   /// Id for an event Perfetto expects to verify the trace viewer is ready.
   ping('PING'),
@@ -54,7 +58,7 @@ enum EmbeddedPerfettoEvent {
   /// re-initialized.
   reloadCssConstants('RELOAD-CSS-CONSTANTS'),
 
-  /// Id for a [postMessage] request that is sent before trying to change the
+  /// Id for a `postMessage` request that is sent before trying to change the
   /// DevTools theme (see [devtoolsThemeChange]).
   ///
   /// Once the DevTools theme handler in the bundled Perfetto web app has been
@@ -63,11 +67,11 @@ enum EmbeddedPerfettoEvent {
   ///
   /// This message must be sent with the argument 'perfettoIgnore' set to true
   /// so that the message handler in the Perfetto codebase
-  /// [post_message_handler.ts] will not try to handle this message and warn
+  /// `post_message_handler.ts` will not try to handle this message and warn
   /// "Unknown postMessage() event received".
   devtoolsThemePing('DART-DEVTOOLS-THEME-PING'),
 
-  /// Id for a [postMessage] response that should be received when the DevTools
+  /// Id for a `postMessage` response that should be received when the DevTools
   /// theme handler has been registered.
   ///
   /// We will send a "ping" event [devtoolsThemePing] to the DevTools theme
@@ -76,11 +80,11 @@ enum EmbeddedPerfettoEvent {
   /// before we can send a theme change request [devtoolsThemeChange].
   devtoolsThemePong('DART-DEVTOOLS-THEME-PONG'),
 
-  /// Id for a [postMessage] request that is sent on DevTools theme changes.
+  /// Id for a `postMessage` request that is sent on DevTools theme changes.
   ///
   /// This message must be sent with the argument 'perfettoIgnore' set to true
   /// so that the message handler in the Perfetto codebase
-  /// [post_message_handler.ts] will not try to handle this message and warn
+  /// `post_message_handler.ts` will not try to handle this message and warn
   /// "Unknown postMessage() event received".
   devtoolsThemeChange('DART-DEVTOOLS-THEME-CHANGE');
 

packages/devtools_app/lib/src/screens/performance/panes/timeline_events/perfetto/_perfetto_web.dart

@@ -109,13 +109,13 @@ class _PerfettoViewController extends DisposableController
   bool _perfettoIFrameUnloaded = false;
 
   /// Completes when the Perfetto postMessage handler is ready, which is
-  /// signaled by receiving a [_perfettoPong] event in response to sending a
-  /// [_perfettoPing] event.
+  /// signaled by receiving a `_perfettoPong` event in response to sending a
+  /// `_perfettoPing` event.
   late final Completer<void> _perfettoHandlerReady;
 
   /// Completes when the DevTools theme postMessage handler is ready, which is
-  /// signaled by receiving a [_devtoolsThemePong] event in response to sending
-  /// a [_devtoolsThemePing] event.
+  /// signaled by receiving a `_devtoolsThemePong` event in response to sending
+  /// a `_devtoolsThemePing` event.
   late final Completer<void> _devtoolsThemeHandlerReady;
 
   /// Timer that will poll until [_perfettoHandlerReady] is complete or until

packages/devtools_app/lib/src/screens/profiler/cpu_profile_model.dart

@@ -550,7 +550,7 @@ class CpuProfileData with Serializable {
 
   factory CpuProfileData.empty() => CpuProfileData.fromJson({});
 
-  /// Generates [CpuProfileData] from the provided [CpuSamples].
+  /// Generates [CpuProfileData] from the provided [cpuSamples].
   ///
   /// [isolateId] The isolate id which was used to get the [cpuSamples].
   /// This will be used to tag the stack frames and trace events.
@@ -1015,9 +1015,8 @@ class CpuStackFrame extends TreeNode<CpuStackFrame>
   /// profile, changing the exclusive counts.
   ///
   /// When [copySampleCounts] is true, inclusive sample counts are also reset
-  /// by default, unless [resetInclusiveSampleCount] is also set to false.
-  /// Inclusive sample counts should only be copied as part of a deep copy of
-  /// a tree.
+  /// by default. Inclusive sample counts should only be copied as part of a
+  /// deep copy of a tree.
   @override
   CpuStackFrame shallowCopy({
     String? id,
@@ -1063,7 +1062,7 @@ class CpuStackFrame extends TreeNode<CpuStackFrame>
     return copy;
   }
 
-  /// Whether [this] stack frame matches another stack frame [other].
+  /// Whether `this` stack frame matches another stack frame [other].
   ///
   /// Two stack frames are said to be matching if they share the following
   /// properties.