From b13f50a91877000d5f4ae4ac3fe9d8404bf885e9 Mon Sep 17 00:00:00 2001 From: Michael Goderbauer Date: Thu, 11 Jul 2024 11:30:26 -0700 Subject: [PATCH] docimports for flutter_driver (#151267) Part of https://github.com/flutter/flutter/issues/150800 --- packages/flutter_driver/lib/driver_extension.dart | 2 ++ .../lib/src/common/deserialization_factory.dart | 2 +- .../lib/src/common/diagnostics_tree.dart | 3 +++ packages/flutter_driver/lib/src/common/find.dart | 10 ++++++++-- packages/flutter_driver/lib/src/common/gesture.dart | 3 +++ .../flutter_driver/lib/src/common/handler_factory.dart | 3 +++ packages/flutter_driver/lib/src/common/health.dart | 3 +++ packages/flutter_driver/lib/src/common/layer_tree.dart | 3 +++ packages/flutter_driver/lib/src/common/message.dart | 3 +++ .../flutter_driver/lib/src/common/render_tree.dart | 3 +++ packages/flutter_driver/lib/src/common/wait.dart | 3 +++ packages/flutter_driver/lib/src/driver/driver.dart | 9 ++++++++- .../frame_request_pending_latency_summarizer.dart | 4 ++-- .../flutter_driver/lib/src/driver/gc_summarizer.dart | 2 +- .../lib/src/driver/profiling_summarizer.dart | 2 +- .../lib/src/driver/raster_cache_summarizer.dart | 2 +- .../lib/src/driver/refresh_rate_summarizer.dart | 2 +- .../lib/src/driver/scene_display_lag_summarizer.dart | 2 +- .../lib/src/driver/vmservice_driver.dart | 9 ++++++--- .../lib/src/driver/vsync_frame_lag_summarizer.dart | 2 +- .../lib/src/extension/_extension_io.dart | 4 ---- .../lib/src/extension/_extension_web.dart | 4 ---- .../flutter_driver/lib/src/extension/extension.dart | 3 +++ .../lib/src/extension/wait_conditions.dart | 6 +++--- 24 files changed, 63 insertions(+), 26 deletions(-) diff --git a/packages/flutter_driver/lib/driver_extension.dart b/packages/flutter_driver/lib/driver_extension.dart index b83126db9e..bf829d779e 100644 --- a/packages/flutter_driver/lib/driver_extension.dart +++ b/packages/flutter_driver/lib/driver_extension.dart @@ -22,6 +22,8 @@ /// enableFlutterDriverExtension(); /// runApp(ExampleApp()); /// } +/// +/// @docImport 'src/extension/extension.dart'; library flutter_driver_extension; export 'src/common/deserialization_factory.dart'; diff --git a/packages/flutter_driver/lib/src/common/deserialization_factory.dart b/packages/flutter_driver/lib/src/common/deserialization_factory.dart index 6be02b5f43..89920b0dc1 100644 --- a/packages/flutter_driver/lib/src/common/deserialization_factory.dart +++ b/packages/flutter_driver/lib/src/common/deserialization_factory.dart @@ -18,7 +18,7 @@ import 'text.dart'; import 'text_input_action.dart'; import 'wait.dart'; -/// A factory for deserializing [Finder]s. +/// A factory for deserializing [SerializableFinder]s. mixin DeserializeFinderFactory { /// Deserializes the finder from JSON generated by [SerializableFinder.serialize]. SerializableFinder deserializeFinder(Map json) { diff --git a/packages/flutter_driver/lib/src/common/diagnostics_tree.dart b/packages/flutter_driver/lib/src/common/diagnostics_tree.dart index dbe5b649de..cb4be00fe6 100644 --- a/packages/flutter_driver/lib/src/common/diagnostics_tree.dart +++ b/packages/flutter_driver/lib/src/common/diagnostics_tree.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. +/// @docImport 'package:flutter/foundation.dart'; +library; + import 'enum_util.dart'; import 'find.dart'; import 'message.dart'; diff --git a/packages/flutter_driver/lib/src/common/find.dart b/packages/flutter_driver/lib/src/common/find.dart index d2c0e00571..c81cf4ffbd 100644 --- a/packages/flutter_driver/lib/src/common/find.dart +++ b/packages/flutter_driver/lib/src/common/find.dart @@ -2,6 +2,12 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +/// @docImport 'package:flutter/semantics.dart'; +/// @docImport 'package:flutter/widgets.dart'; +/// @docImport 'package:flutter_driver/flutter_driver.dart'; +/// @docImport 'package:flutter_test/flutter_test.dart'; +library; + import 'dart:convert'; import 'package:meta/meta.dart'; @@ -174,12 +180,12 @@ class BySemanticsLabel extends SerializableFinder { } /// A Flutter Driver finder that finds widgets by [text] inside a -/// [widgets.Text] or [widgets.EditableText] widget. +/// [Text] or [EditableText] widget. class ByText extends SerializableFinder { /// Creates a text finder given the text. const ByText(this.text); - /// The text that appears inside the [widgets.Text] or [widgets.EditableText] + /// The text that appears inside the [Text] or [EditableText] /// widget. final String text; diff --git a/packages/flutter_driver/lib/src/common/gesture.dart b/packages/flutter_driver/lib/src/common/gesture.dart index 22426df90e..71d9e31949 100644 --- a/packages/flutter_driver/lib/src/common/gesture.dart +++ b/packages/flutter_driver/lib/src/common/gesture.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. +/// @docImport 'package:flutter/widgets.dart'; +library; + import 'find.dart'; /// A Flutter Driver command that taps on a target widget located by [finder]. diff --git a/packages/flutter_driver/lib/src/common/handler_factory.dart b/packages/flutter_driver/lib/src/common/handler_factory.dart index 6afbebe242..0446b3c6d8 100644 --- a/packages/flutter_driver/lib/src/common/handler_factory.dart +++ b/packages/flutter_driver/lib/src/common/handler_factory.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. +/// @docImport 'package:flutter_driver/flutter_driver.dart'; +library; + import 'dart:async'; import 'package:flutter/cupertino.dart'; diff --git a/packages/flutter_driver/lib/src/common/health.dart b/packages/flutter_driver/lib/src/common/health.dart index c0a400f8ff..1459eeea8a 100644 --- a/packages/flutter_driver/lib/src/common/health.dart +++ b/packages/flutter_driver/lib/src/common/health.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. +/// @docImport 'package:flutter_driver/flutter_driver.dart'; +library; + import 'enum_util.dart'; import 'message.dart'; diff --git a/packages/flutter_driver/lib/src/common/layer_tree.dart b/packages/flutter_driver/lib/src/common/layer_tree.dart index 18419f24ca..86b5184612 100644 --- a/packages/flutter_driver/lib/src/common/layer_tree.dart +++ b/packages/flutter_driver/lib/src/common/layer_tree.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. +/// @docImport 'package:flutter_driver/flutter_driver.dart'; +library; + import 'message.dart'; /// A Flutter Driver command that requests a string representation of the layer tree. diff --git a/packages/flutter_driver/lib/src/common/message.dart b/packages/flutter_driver/lib/src/common/message.dart index ae90cab5f6..133b5fe756 100644 --- a/packages/flutter_driver/lib/src/common/message.dart +++ b/packages/flutter_driver/lib/src/common/message.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. +/// @docImport 'package:flutter/widgets.dart'; +library; + import 'package:meta/meta.dart'; /// An object sent from the Flutter Driver to a Flutter application to instruct diff --git a/packages/flutter_driver/lib/src/common/render_tree.dart b/packages/flutter_driver/lib/src/common/render_tree.dart index 0477f4d310..201ce9d12e 100644 --- a/packages/flutter_driver/lib/src/common/render_tree.dart +++ b/packages/flutter_driver/lib/src/common/render_tree.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. +/// @docImport 'package:flutter_driver/flutter_driver.dart'; +library; + import 'message.dart'; /// A Flutter Driver command that requests a string representation of the render tree. diff --git a/packages/flutter_driver/lib/src/common/wait.dart b/packages/flutter_driver/lib/src/common/wait.dart index b3b6201cbb..30217e1a38 100644 --- a/packages/flutter_driver/lib/src/common/wait.dart +++ b/packages/flutter_driver/lib/src/common/wait.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. +/// @docImport 'package:flutter/widgets.dart'; +library; + import 'dart:convert'; import 'message.dart'; diff --git a/packages/flutter_driver/lib/src/driver/driver.dart b/packages/flutter_driver/lib/src/driver/driver.dart index 408a228544..50a9dd793c 100644 --- a/packages/flutter_driver/lib/src/driver/driver.dart +++ b/packages/flutter_driver/lib/src/driver/driver.dart @@ -2,6 +2,13 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +/// @docImport 'package:flutter/services.dart'; +/// @docImport 'package:flutter/widgets.dart'; +/// @docImport 'package:flutter_driver/driver_extension.dart'; + +/// @docImport 'package:flutter_test/flutter_test.dart'; +library; + import 'dart:io'; import 'package:meta/meta.dart'; @@ -762,7 +769,7 @@ abstract class FlutterDriver { class CommonFinders { const CommonFinders._(); - /// Finds [widgets.Text] and [widgets.EditableText] widgets containing string + /// Finds [Text] and [EditableText] widgets containing string /// equal to [text]. SerializableFinder text(String text) => ByText(text); diff --git a/packages/flutter_driver/lib/src/driver/frame_request_pending_latency_summarizer.dart b/packages/flutter_driver/lib/src/driver/frame_request_pending_latency_summarizer.dart index 2554611103..96a334d565 100644 --- a/packages/flutter_driver/lib/src/driver/frame_request_pending_latency_summarizer.dart +++ b/packages/flutter_driver/lib/src/driver/frame_request_pending_latency_summarizer.dart @@ -8,7 +8,7 @@ import 'timeline.dart'; /// Event name for frame request pending timeline events. const String kFrameRequestPendingEvent = 'Frame Request Pending'; -/// Summarizes [TimelineEvents]s corresponding to [kFrameRequestPendingEvent] events. +/// Summarizes [TimelineEvent]s corresponding to [kFrameRequestPendingEvent] events. /// /// `FrameRequestPendingLatency` is the time between `Animator::RequestFrame` /// and `Animator::BeginFrame` for each frame built by the Flutter engine. @@ -16,7 +16,7 @@ class FrameRequestPendingLatencySummarizer { /// Creates a FrameRequestPendingLatencySummarizer given the timeline events. FrameRequestPendingLatencySummarizer(this.frameRequestPendingEvents); - /// Timeline events with names in [kFrameRequestPendingTimelineEventNames]. + /// Timeline events with names in [kFrameRequestPendingEvent]. final List frameRequestPendingEvents; /// Computes the average `FrameRequestPendingLatency` over the period of the timeline. diff --git a/packages/flutter_driver/lib/src/driver/gc_summarizer.dart b/packages/flutter_driver/lib/src/driver/gc_summarizer.dart index 36abab586c..11062a4552 100644 --- a/packages/flutter_driver/lib/src/driver/gc_summarizer.dart +++ b/packages/flutter_driver/lib/src/driver/gc_summarizer.dart @@ -14,7 +14,7 @@ const Set kGCRootEvents = { 'StartConcurrentMark', }; -/// Summarizes [TimelineEvents]s corresponding to [kGCRootEvents] category. +/// Summarizes [TimelineEvent]s corresponding to [kGCRootEvents] category. /// /// A sample event (some fields have been omitted for brevity): /// ```json diff --git a/packages/flutter_driver/lib/src/driver/profiling_summarizer.dart b/packages/flutter_driver/lib/src/driver/profiling_summarizer.dart index 0d4b464164..bee1a34e1c 100644 --- a/packages/flutter_driver/lib/src/driver/profiling_summarizer.dart +++ b/packages/flutter_driver/lib/src/driver/profiling_summarizer.dart @@ -33,7 +33,7 @@ enum ProfileType { Memory, } -/// Summarizes [TimelineEvents]s corresponding to [kProfilingEvents] category. +/// Summarizes [TimelineEvent]s corresponding to [kProfilingEvents] category. /// /// A sample event (some fields have been omitted for brevity): /// ```json diff --git a/packages/flutter_driver/lib/src/driver/raster_cache_summarizer.dart b/packages/flutter_driver/lib/src/driver/raster_cache_summarizer.dart index 3ae673d270..30677b88da 100644 --- a/packages/flutter_driver/lib/src/driver/raster_cache_summarizer.dart +++ b/packages/flutter_driver/lib/src/driver/raster_cache_summarizer.dart @@ -13,7 +13,7 @@ const String _kLayerMemory = 'LayerMBytes'; const String _kPictureCount = 'PictureCount'; const String _kPictureMemory = 'PictureMBytes'; -/// Summarizes [TimelineEvents]s corresponding to [kRasterCacheEvent] events. +/// Summarizes [TimelineEvent]s corresponding to [kRasterCacheEvent] events. /// /// A sample event (some fields have been omitted for brevity): /// ```json diff --git a/packages/flutter_driver/lib/src/driver/refresh_rate_summarizer.dart b/packages/flutter_driver/lib/src/driver/refresh_rate_summarizer.dart index 9a42500398..b3021f75f6 100644 --- a/packages/flutter_driver/lib/src/driver/refresh_rate_summarizer.dart +++ b/packages/flutter_driver/lib/src/driver/refresh_rate_summarizer.dart @@ -7,7 +7,7 @@ import 'timeline.dart'; /// Event name for refresh rate related timeline events. const String kUIThreadVsyncProcessEvent = 'VsyncProcessCallback'; -/// A summary of [TimelineEvents]s corresponding to `kUIThreadVsyncProcessEvent` events. +/// A summary of [TimelineEvent]s corresponding to `kUIThreadVsyncProcessEvent` events. /// /// `RefreshRate` is the time between the start of a vsync pulse and the target time of that vsync. class RefreshRateSummary { diff --git a/packages/flutter_driver/lib/src/driver/scene_display_lag_summarizer.dart b/packages/flutter_driver/lib/src/driver/scene_display_lag_summarizer.dart index 6dd2023e84..dd61fbc313 100644 --- a/packages/flutter_driver/lib/src/driver/scene_display_lag_summarizer.dart +++ b/packages/flutter_driver/lib/src/driver/scene_display_lag_summarizer.dart @@ -10,7 +10,7 @@ const String kSceneDisplayLagEvent = 'SceneDisplayLag'; const String _kVsyncTransitionsMissed = 'vsync_transitions_missed'; -/// Summarizes [TimelineEvents]s corresponding to [kSceneDisplayLagEvent] events. +/// Summarizes [TimelineEvent]s corresponding to [kSceneDisplayLagEvent] events. /// /// A sample event (some fields have been omitted for brevity): /// ```json diff --git a/packages/flutter_driver/lib/src/driver/vmservice_driver.dart b/packages/flutter_driver/lib/src/driver/vmservice_driver.dart index c91596076c..0b62f45a54 100644 --- a/packages/flutter_driver/lib/src/driver/vmservice_driver.dart +++ b/packages/flutter_driver/lib/src/driver/vmservice_driver.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. +/// @docImport 'dart:developer'; +library; + import 'dart:async'; import 'dart:convert'; import 'dart:io'; @@ -281,7 +284,7 @@ class VMServiceFlutterDriver extends FlutterDriver { /// Client connected to the Dart VM running the Flutter application. /// - /// You can use [VMServiceClient] to check VM version, flags and get + /// You can use [vms.VmService] to check VM version, flags and get /// notified when a new isolate has been instantiated. That could be /// useful if your application spawns multiple isolates that you /// would like to instrument. @@ -297,7 +300,7 @@ class VMServiceFlutterDriver extends FlutterDriver { /// /// If you used the [registerExtension] API to instrument your application, /// you can use this [vms.Isolate] to call these extension methods via - /// [invokeExtension]. + /// [vms.Isolate.invokeExtension]. final vms.Isolate _appIsolate; /// Whether to print communication between host and app to `stdout`. @@ -554,7 +557,7 @@ String _getWebSocketUrl(String url) { } /// Waits for a real Dart VM service to become available, then connects using -/// the [VMServiceClient]. +/// the [vms.VmService]. Future _waitAndConnect(String url, Map? headers) async { final String webSocketUrl = _getWebSocketUrl(url); int attempts = 0; diff --git a/packages/flutter_driver/lib/src/driver/vsync_frame_lag_summarizer.dart b/packages/flutter_driver/lib/src/driver/vsync_frame_lag_summarizer.dart index 9fe2c50458..6456ac8a68 100644 --- a/packages/flutter_driver/lib/src/driver/vsync_frame_lag_summarizer.dart +++ b/packages/flutter_driver/lib/src/driver/vsync_frame_lag_summarizer.dart @@ -14,7 +14,7 @@ const Set kVsyncTimelineEventNames = { _kPlatformVsyncEvent, }; -/// Summarizes [TimelineEvents]s corresponding to [kVsyncTimelineEventNames] events. +/// Summarizes [TimelineEvent]s corresponding to [kVsyncTimelineEventNames] events. /// /// `VsyncFrameLag` is the time between when a platform vsync event is received to /// when the frame starts getting processed by the Flutter Engine. This delay is diff --git a/packages/flutter_driver/lib/src/extension/_extension_io.dart b/packages/flutter_driver/lib/src/extension/_extension_io.dart index 9ad5bff06f..2b59f4aa72 100644 --- a/packages/flutter_driver/lib/src/extension/_extension_io.dart +++ b/packages/flutter_driver/lib/src/extension/_extension_io.dart @@ -3,10 +3,6 @@ // found in the LICENSE file. /// The dart:io implementation of [registerWebServiceExtension]. -/// -/// See also: -/// -/// * [_extension_web.dart], which has the web implementation void registerWebServiceExtension(Future> Function(Map) call) { throw UnsupportedError('Use registerServiceExtension instead'); } diff --git a/packages/flutter_driver/lib/src/extension/_extension_web.dart b/packages/flutter_driver/lib/src/extension/_extension_web.dart index fc44a0a01a..5648f0350c 100644 --- a/packages/flutter_driver/lib/src/extension/_extension_web.dart +++ b/packages/flutter_driver/lib/src/extension/_extension_web.dart @@ -15,10 +15,6 @@ external JSObject get _window; /// /// window.$flutterDriver will be called by Flutter Web Driver to process /// Flutter Command. -/// -/// See also: -/// -/// * [_extension_io.dart], which has the dart:io implementation void registerWebServiceExtension(Future> Function(Map) call) { // Define the result variable because packages/flutter_driver/lib/src/driver/web_driver.dart // checks for this value to become non-null when waiting for the result. If this value is diff --git a/packages/flutter_driver/lib/src/extension/extension.dart b/packages/flutter_driver/lib/src/extension/extension.dart index c21b3b88d5..88b297ff90 100644 --- a/packages/flutter_driver/lib/src/extension/extension.dart +++ b/packages/flutter_driver/lib/src/extension/extension.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. +/// @docImport 'package:flutter_driver/flutter_driver.dart'; +library; + import 'dart:async'; import 'package:flutter/cupertino.dart'; diff --git a/packages/flutter_driver/lib/src/extension/wait_conditions.dart b/packages/flutter_driver/lib/src/extension/wait_conditions.dart index 7df3c6bac0..8fcfe84fec 100644 --- a/packages/flutter_driver/lib/src/extension/wait_conditions.dart +++ b/packages/flutter_driver/lib/src/extension/wait_conditions.dart @@ -37,7 +37,7 @@ class _InternalNoTransientCallbacksCondition implements WaitCondition { /// Creates an [_InternalNoTransientCallbacksCondition] instance. const _InternalNoTransientCallbacksCondition(); - /// Factory constructor to parse an [InternalNoTransientCallbacksCondition] + /// Factory constructor to parse an [_InternalNoTransientCallbacksCondition] /// instance from the given [SerializableWaitCondition] instance. factory _InternalNoTransientCallbacksCondition.deserialize(SerializableWaitCondition condition) { if (condition.conditionName != 'NoTransientCallbacksCondition') { @@ -63,7 +63,7 @@ class _InternalNoPendingFrameCondition implements WaitCondition { /// Creates an [_InternalNoPendingFrameCondition] instance. const _InternalNoPendingFrameCondition(); - /// Factory constructor to parse an [InternalNoPendingFrameCondition] instance + /// Factory constructor to parse an [_InternalNoPendingFrameCondition] instance /// from the given [SerializableWaitCondition] instance. factory _InternalNoPendingFrameCondition.deserialize(SerializableWaitCondition condition) { if (condition.conditionName != 'NoPendingFrameCondition') { @@ -89,7 +89,7 @@ class _InternalFirstFrameRasterizedCondition implements WaitCondition { /// Creates an [_InternalFirstFrameRasterizedCondition] instance. const _InternalFirstFrameRasterizedCondition(); - /// Factory constructor to parse an [InternalNoPendingFrameCondition] instance + /// Factory constructor to parse an [_InternalFirstFrameRasterizedCondition] instance /// from the given [SerializableWaitCondition] instance. factory _InternalFirstFrameRasterizedCondition.deserialize(SerializableWaitCondition condition) { if (condition.conditionName != 'FirstFrameRasterizedCondition') {