Fix broken comment references in devtools_app_shared (#8863)
diff --git a/packages/devtools_app_shared/example/ui/dialog_example.dart b/packages/devtools_app_shared/example/ui/dialog_example.dart index 00fd32d..3100916 100644 --- a/packages/devtools_app_shared/example/ui/dialog_example.dart +++ b/packages/devtools_app_shared/example/ui/dialog_example.dart
@@ -5,7 +5,7 @@ import 'package:devtools_app_shared/ui.dart' as devtools_shared_ui; import 'package:flutter/material.dart'; -/// Example of using a [DevToolsDialog] widget from +/// Example of using a [devtools_shared_ui.DevToolsDialog] widget from /// 'package:devtools_app_shared/ui.dart'. class MyDialog extends StatelessWidget { const MyDialog({super.key});
diff --git a/packages/devtools_app_shared/example/ui/split_example.dart b/packages/devtools_app_shared/example/ui/split_example.dart index 114d29b..ef3f832 100644 --- a/packages/devtools_app_shared/example/ui/split_example.dart +++ b/packages/devtools_app_shared/example/ui/split_example.dart
@@ -5,12 +5,12 @@ import 'package:devtools_app_shared/ui.dart' as devtools_shared_ui; import 'package:flutter/material.dart'; -/// Example of using the [SplitPane] widget from +/// Example of using the [devtools_shared_ui.SplitPane] widget from /// 'package:devtools_app_shared/ui.dart' with two children laid across a /// horizontal axis. /// -/// This example does not specify the [SplitPane.splitters] parameter, so a -/// default splitter is used. +/// This example does not specify the [devtools_shared_ui.SplitPane.splitters] +/// parameter, so a default splitter is used. class SplitExample extends StatelessWidget { const SplitExample({super.key}); @@ -28,7 +28,7 @@ } } -/// Example of using the [SplitPane] widget from +/// Example of using the [devtools_shared_ui.SplitPane] widget from /// 'package:devtools_app_shared/ui.dart' with three children laid across a /// vertical axis. ///
diff --git a/packages/devtools_app_shared/lib/src/service/resolved_uri_manager.dart b/packages/devtools_app_shared/lib/src/service/resolved_uri_manager.dart index 8998bfe..aaed614 100644 --- a/packages/devtools_app_shared/lib/src/service/resolved_uri_manager.dart +++ b/packages/devtools_app_shared/lib/src/service/resolved_uri_manager.dart
@@ -44,13 +44,14 @@ } } - /// Calls out to the [VMService] to lookup package uri to full file path - /// mappings + /// Calls out to the [VmService] to lookup package URI to full file path + /// mappings. /// /// Known mappings are cached to avoid asking [VmService] redundantly. /// - /// [isolateId] The id of the isolate that the [packageUris] were generated on. - /// [packageUris] List of uris to fetch full file paths for. + /// * [isolateId] - The ID of the isolate that the [packageUris] were + /// generated on. + /// * [packageUris] - List of URIs to fetch full file paths for. Future<void> fetchFileUris(String isolateId, List<String> packageUris) async { if (_packagePathMappings != null) { final fileUris = @@ -69,10 +70,11 @@ } } - /// Returns a package uri for the given uri, if one exists in the cache. + /// Returns a package URI for the given URI, if one exists in the cache. /// - /// [isolateId] The id of the isolate that the [uris] were generated on. - /// [uri] Absolute path uri to look up in the package uri mapping cache. + /// * [isolateId] - The id of the isolate that the URIs were generated on. + /// * [fileUri] - Absolute path uri to look up in the package uri mapping + /// cache. String? lookupPackageUri(String isolateId, String fileUri) => _packagePathMappings?.lookupFullPathToPackageMapping(isolateId, fileUri);
diff --git a/packages/devtools_app_shared/lib/src/ui/common.dart b/packages/devtools_app_shared/lib/src/ui/common.dart index 5f07e88..52d5c24 100644 --- a/packages/devtools_app_shared/lib/src/ui/common.dart +++ b/packages/devtools_app_shared/lib/src/ui/common.dart
@@ -163,7 +163,8 @@ /// Wraps [child] in a rounded border with default styling. /// /// This border can optionally be made non-uniform by setting any of -/// [showTop], [showBottom], [showLeft] or [showRight] to false. +/// [showTopLeft], [showTopRight], [showBottomLeft], or [showBottomRight] to +/// false. /// /// If [clip] is true, the child will be wrapped in a [ClipRRect] to ensure the /// rounded corner of the border is drawn as expected. This should not be @@ -562,7 +563,8 @@ } } -/// A text span that will launch the provided URL from [link] when clicked. +/// A text span that, when clicked, will launch the provided URL from the `link` +/// given in the constructor. class LinkTextSpan extends TextSpan { LinkTextSpan({ required Link link,
diff --git a/packages/devtools_app_shared/lib/src/ui/flex_split_column.dart b/packages/devtools_app_shared/lib/src/ui/flex_split_column.dart index 72bb16c..5b39be9 100644 --- a/packages/devtools_app_shared/lib/src/ui/flex_split_column.dart +++ b/packages/devtools_app_shared/lib/src/ui/flex_split_column.dart
@@ -2,25 +2,28 @@ // 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 'package:devtools_app_shared/src/ui/common.dart'; +library; + import 'package:flutter/material.dart'; import 'split_pane.dart'; -/// A widget that takes a list of [children] and lays them out in a column where +/// A widget that takes a list of `children` and lays them out in a column where /// each child has a flexible height. /// -/// Each child in [children] must have an accompanying header in [header]. Since -/// each header must be a [PreferredSizeWidget], it is common to use the shared -/// widgets [AreaPaneHeader] or [BlankHeader] for the column [headers]. +/// Each child in `children` must have an accompanying header in [headers]. +/// Since each header must be a [PreferredSizeWidget], it is common to use the +/// shared widgets [AreaPaneHeader] or [BlankHeader] for the column [headers]. /// /// The user can customize the amount of space allocated to each child by -/// clicking and dragging the [header]s that separate the children. +/// clicking and dragging the [headers] that separate the children. /// -/// [initialFractions] defines how much space to give each child when building -/// this widget. +/// The constructor's `initialFractions` parameter defines how much space to +/// give each child when building this widget. /// -/// [minSizes] defines the minimum size that each child can be set to when -/// adjusting the sizes of the children. +/// The constructor's `minSizes` defines the minimum size that each child can be +/// set to when adjusting the sizes of the children. final class FlexSplitColumn extends StatelessWidget { FlexSplitColumn({ super.key, @@ -42,45 +45,45 @@ _minSizes = modifyMinSizesToIncludeFirstHeader(minSizes, headers); /// The headers that will be laid out above each corresponding child in - /// [children]. + /// `children`. /// /// All headers but the first will be passed into [SplitPane.splitters] when /// creating the [SplitPane] widget in `build`. Instead of being passed into - /// [SplitPane.splitters], it will be combined with the first child in [children] + /// [SplitPane.splitters], it will be combined with the first child in `children` /// to create the first child we will pass into [SplitPane.children]. /// /// We do this because the first header will not actually be a splitter as /// there is not any content above it for it to split. /// /// We modify other values [_children], [_initialFractions], and [_minSizes] - /// from [children], [initialFractions], and [minSizes], respectively, to + /// from `children`, `initialFractions`, and `minSizes`, respectively, to /// account for the first header. We do this adjustment here so that the /// creators of [FlexSplitColumn] can be unaware of the under-the-hood /// calculations necessary to achieve the UI requirements specified by - /// [initialFractions] and [minSizes]. + /// `initialFractions` and `minSizes`. final List<PreferredSizeWidget> headers; /// The children that will be laid out below each corresponding header in /// [headers]. /// - /// All [children] except the first will be passed into [SplitPane.children] - /// unmodified. We need to modify the first child from [children] to account + /// All `children` except the first will be passed into [SplitPane.children] + /// unmodified. We need to modify the first child from `children` to account /// for the first header (see above). final List<Widget> _children; - /// The fraction of the layout to allocate to each child in [children]. + /// The fraction of the layout to allocate to each child in `children`. /// - /// We need to modify the values given by [initialFractions] to account for + /// We need to modify the values given by `initialFractions` to account for /// the first header (see above). final List<double> _initialFractions; /// The minimum size each child is allowed to be. /// - /// We need to modify the values given by [minSizes] to account for the first + /// We need to modify the values given by `minSizes` to account for the first /// header (see above). final List<double> _minSizes; - /// The total height of the column, including all [headers] and [children]. + /// The total height of the column, including all [headers] and `children`. final double totalHeight; @visibleForTesting
diff --git a/packages/devtools_app_shared/lib/src/utils/auto_dispose.dart b/packages/devtools_app_shared/lib/src/utils/auto_dispose.dart index c278280..7df0500 100644 --- a/packages/devtools_app_shared/lib/src/utils/auto_dispose.dart +++ b/packages/devtools_app_shared/lib/src/utils/auto_dispose.dart
@@ -120,8 +120,8 @@ final _listenables = <Listenable>[]; final _listeners = <VoidCallback>[]; - /// An [Expando] that tracks listener ids when [addAutoDisposeListener] is - /// called with a non-null [id] parameter. + /// An [Expando] that tracks listener IDs when [addAutoDisposeListener] is + /// called with a non-null `id` parameter. final _listenerIdExpando = Expando<String>(); /// Track a stream subscription to be automatically cancelled on dispose. @@ -166,8 +166,8 @@ /// /// It is fine to call this method and then add additional listeners. /// - /// If [excludeIds] is non-empty, any listeners that have an associated id - /// from [_listenersById] will not be cancelled. + /// If [excludeIds] is non-empty, any listeners that have an associated ID + /// from [_listenerIdExpando] will not be cancelled. void cancelListeners({List<String> excludeIds = const <String>[]}) { assert(_listenables.length == _listeners.length); final skipCancelIndices = <int>[];
diff --git a/packages/devtools_app_shared/lib/src/utils/list.dart b/packages/devtools_app_shared/lib/src/utils/list.dart index d4dc274..87faf9e 100644 --- a/packages/devtools_app_shared/lib/src/utils/list.dart +++ b/packages/devtools_app_shared/lib/src/utils/list.dart
@@ -92,10 +92,10 @@ /// Truncates to just the elements between [start] and [end]. /// - /// If [end] is omitted, it defaults to the [length] of this list. + /// If [end] is omitted, it defaults to the `length` of this list. /// /// The `start` and `end` positions must satisfy the relations - /// 0 ≤ `start` ≤ `end` ≤ [length] + /// 0 ≤ `start` ≤ `end` ≤ `length`. /// If `end` is equal to `start`, then the returned list is empty. void trimToSublist(int start, [int? end]) { // TODO(jacobr): use a more sophisticated data structure such as