diff --git a/packages/flutter/lib/src/foundation/_capabilities_web.dart b/packages/flutter/lib/src/foundation/_capabilities_web.dart index 35ac3df45e0..139333f3574 100644 --- a/packages/flutter/lib/src/foundation/_capabilities_web.dart +++ b/packages/flutter/lib/src/foundation/_capabilities_web.dart @@ -12,8 +12,8 @@ external JSAny? get _windowFlutterCanvasKit; @JS('window._flutter_skwasmInstance') external JSAny? get _skwasmInstance; -/// The web implementation of [isCanvasKit] +/// The web implementation of [isCanvasKit]. bool get isCanvasKit => _windowFlutterCanvasKit != null; -/// The web implementation of [isSkwasm] +/// The web implementation of [isSkwasm]. bool get isSkwasm => _skwasmInstance != null; diff --git a/packages/flutter/lib/src/foundation/assertions.dart b/packages/flutter/lib/src/foundation/assertions.dart index 68d4bb3f56a..5f20a4d80ec 100644 --- a/packages/flutter/lib/src/foundation/assertions.dart +++ b/packages/flutter/lib/src/foundation/assertions.dart @@ -99,8 +99,8 @@ class PartialStackFrame { /// A class that filters stack frames for additional filtering on /// [FlutterError.defaultStackFilter]. abstract class StackFilter { - /// Abstract const constructor. This constructor enables subclasses to provide - /// const constructors so that they can be used in const expressions. + /// This constructor enables subclasses to provide const constructors so that + /// they can be used in const expressions. const StackFilter(); /// Filters the list of [StackFrame]s by updating corresponding indices in @@ -121,8 +121,7 @@ abstract class StackFilter { /// * [PartialStackFrame], a class that helps match partial method information /// to a stack frame. class RepetitiveStackFrameFilter extends StackFilter { - /// Creates a new RepetitiveStackFrameFilter. All parameters are required and must not be - /// null. + /// Creates a new RepetitiveStackFrameFilter. const RepetitiveStackFrameFilter({required this.frames, required this.replacement}); /// The shape of this repetitive stack pattern. @@ -435,8 +434,10 @@ class FlutterErrorDetails with Diagnosticable { static final List propertiesTransformers = []; - /// The exception. Often this will be an [AssertionError], maybe specifically - /// a [FlutterError]. However, this could be any value at all. + /// The exception. + /// + /// Often this will be an [AssertionError], maybe specifically a [FlutterError]. + /// However, this could be any value at all. final Object exception; /// The stack trace from where the [exception] was thrown (as opposed to where @@ -452,9 +453,9 @@ class FlutterErrorDetails with Diagnosticable { /// [StackTrace.toString]. final StackTrace? stack; - /// A human-readable brief name describing the library that caught the error - /// message. This is used by the default error handler in the header dumped to - /// the console. + /// A human-readable brief name describing the library that caught the error message. + /// + /// This is used by the default error handler in the header dumped to the console. final String? library; /// A [DiagnosticsNode] that provides a human-readable description of where @@ -498,9 +499,10 @@ class FlutterErrorDetails with Diagnosticable { /// [FlutterErrorDetails]. final DiagnosticsNode? context; - /// A callback which filters the [stack] trace. Receives an iterable of - /// strings representing the frames encoded in the way that - /// [StackTrace.toString()] provides. Should return an iterable of lines to + /// A callback which filters the [stack] trace. + /// + /// Receives an iterable of strings representing the frames encoded in the way + /// that [StackTrace.toString()] provides. Should return an iterable of lines to /// output for the stack. /// /// If this is not provided, then [FlutterError.dumpErrorToConsole] will use diff --git a/packages/flutter/lib/src/foundation/basic_types.dart b/packages/flutter/lib/src/foundation/basic_types.dart index 661c9e90963..3ad1b943c65 100644 --- a/packages/flutter/lib/src/foundation/basic_types.dart +++ b/packages/flutter/lib/src/foundation/basic_types.dart @@ -106,7 +106,9 @@ typedef AsyncValueGetter = Future Function(); /// returned by `where`. class CachingIterable extends IterableBase { /// Creates a [CachingIterable] using the given [Iterator] as the source of - /// data. The iterator must not throw exceptions. + /// data. + /// + /// The iterator must not throw exceptions. /// /// Since the argument is an [Iterator], not an [Iterable], it is /// guaranteed that the underlying data set will only be walked diff --git a/packages/flutter/lib/src/foundation/binding.dart b/packages/flutter/lib/src/foundation/binding.dart index 5e6de58afd5..b42ecd964ff 100644 --- a/packages/flutter/lib/src/foundation/binding.dart +++ b/packages/flutter/lib/src/foundation/binding.dart @@ -182,7 +182,7 @@ abstract class BindingBase { static Type? _debugInitializedType; static bool _debugServiceExtensionsRegistered = false; - /// Deprecated. Will be removed in a future version of Flutter. + /// Deprecated; will be removed in a future version of Flutter. /// /// This property has been deprecated to prepare for Flutter's upcoming /// support for multiple views and multiple windows. @@ -248,9 +248,10 @@ abstract class BindingBase { /// different [ui.PlatformDispatcher] implementation. ui.PlatformDispatcher get platformDispatcher => ui.PlatformDispatcher.instance; - /// The initialization method. Subclasses override this method to hook into - /// the platform and otherwise configure their services. Subclasses must call - /// "super.initInstances()". + /// The initialization method. + /// + /// Subclasses override this method to hook into the platform and otherwise + /// configure their services. Subclasses must call "super.initInstances()". /// /// The binding is not fully initialized when this method runs (for /// example, other binding mixins may not yet have run their diff --git a/packages/flutter/lib/src/foundation/bitfield.dart b/packages/flutter/lib/src/foundation/bitfield.dart index 1aeb4504826..9d97b8f183d 100644 --- a/packages/flutter/lib/src/foundation/bitfield.dart +++ b/packages/flutter/lib/src/foundation/bitfield.dart @@ -13,6 +13,7 @@ import '_bitfield_io.dart' if (dart.library.js_interop) '_bitfield_web.dart' as const int kMaxUnsignedSMI = bitfield.kMaxUnsignedSMI; /// A BitField over an enum (or other class whose values implement "index"). +/// /// Only the first 62 values of the enum can be used as indices. /// /// When compiling to JavaScript, this class is not supported. diff --git a/packages/flutter/lib/src/foundation/change_notifier.dart b/packages/flutter/lib/src/foundation/change_notifier.dart index f5ab99c024e..e64570de485 100644 --- a/packages/flutter/lib/src/foundation/change_notifier.dart +++ b/packages/flutter/lib/src/foundation/change_notifier.dart @@ -60,8 +60,8 @@ export 'dart:ui' show VoidCallback; /// notifications whenever any of a list of other [Listenable]s trigger their /// notifications. abstract class Listenable { - /// Abstract const constructor. This constructor enables subclasses to provide - /// const constructors so that they can be used in const expressions. + /// This constructor enables subclasses to provide const constructors so that + /// they can be used in const expressions. const Listenable(); /// Return a [Listenable] that triggers when any of the given [Listenable]s @@ -92,12 +92,14 @@ abstract class Listenable { /// rebuild whenever a [ValueListenable] object triggers its notifications, /// providing the builder with the value of the object. abstract class ValueListenable extends Listenable { - /// Abstract const constructor. This constructor enables subclasses to provide - /// const constructors so that they can be used in const expressions. + /// This constructor enables subclasses to provide const constructors so that + /// they can be used in const expressions. const ValueListenable(); - /// The current value of the object. When the value changes, the callbacks - /// registered with [addListener] will be invoked. + /// The current value of the object. + /// + /// When the value changes, the callbacks registered with [addListener] will be + /// invoked. T get value; } @@ -360,9 +362,10 @@ mixin class ChangeNotifier implements Listenable { } } - /// Discards any resources used by the object. After this is called, the - /// object is not in a usable state and should be discarded (calls to - /// [addListener] will throw after the object is disposed). + /// Discards any resources used by the object. + /// + /// After this is called, the object is not in a usable state and should be + /// discarded (calls to [addListener] will throw after the object is disposed). /// /// This method should only be called by the object's owner. /// diff --git a/packages/flutter/lib/src/foundation/key.dart b/packages/flutter/lib/src/foundation/key.dart index 6c085dd9d8c..afcdd818586 100644 --- a/packages/flutter/lib/src/foundation/key.dart +++ b/packages/flutter/lib/src/foundation/key.dart @@ -49,8 +49,8 @@ abstract class Key { /// /// * [Widget.key], which discusses how widgets use keys. abstract class LocalKey extends Key { - /// Abstract const constructor. This constructor enables subclasses to provide - /// const constructors so that they can be used in const expressions. + /// This constructor enables subclasses to provide const constructors so that + /// they can be used in const expressions. const LocalKey() : super.empty(); } @@ -89,7 +89,7 @@ class ValueKey extends LocalKey { /// Creates a key that delegates its [operator==] to the given value. const ValueKey(this.value); - /// The value to which this key delegates its [operator==] + /// The value to which this key delegates its [operator==]. final T value; @override diff --git a/packages/flutter/lib/src/foundation/licenses.dart b/packages/flutter/lib/src/foundation/licenses.dart index 0d06aa8421e..287124759d1 100644 --- a/packages/flutter/lib/src/foundation/licenses.dart +++ b/packages/flutter/lib/src/foundation/licenses.dart @@ -21,7 +21,9 @@ class LicenseParagraph { /// Creates a string for a license entry paragraph. const LicenseParagraph(this.text, this.indent); - /// The text of the paragraph. Should not have any leading or trailing whitespace. + /// The text of the paragraph. + /// + /// Should not have any leading or trailing whitespace. final String text; /// How many steps of indentation the paragraph has. @@ -47,26 +49,30 @@ class LicenseParagraph { /// demand in [LicenseEntryCollector] callbacks passed to /// [LicenseRegistry.addLicense]. abstract class LicenseEntry { - /// Abstract const constructor. This constructor enables subclasses to provide - /// const constructors so that they can be used in const expressions. + /// This constructor enables subclasses to provide const constructors so that + /// they can be used in const expressions. const LicenseEntry(); /// The names of the packages that this license entry applies to. Iterable get packages; /// The paragraphs of the license, each as a [LicenseParagraph] consisting of - /// a string and some formatting information. Paragraphs can include newline - /// characters, but this is discouraged as it results in ugliness. + /// a string and some formatting information. + /// + /// Paragraphs can include newline characters, but this is discouraged as it + /// results in ugliness. Iterable get paragraphs; } enum _LicenseEntryWithLineBreaksParserState { beforeParagraph, inParagraph } /// Variant of [LicenseEntry] for licenses that separate paragraphs with blank -/// lines and that hard-wrap text within paragraphs. Lines that begin with one -/// or more space characters are also assumed to introduce new paragraphs, -/// unless they start with the same number of spaces as the previous line, in -/// which case it's assumed they are a continuation of an indented paragraph. +/// lines and that hard-wrap text within paragraphs. +/// +/// Lines that begin with one or more space characters are also assumed to +/// introduce new paragraphs, unless they start with the same number of spaces +/// as the previous line, in which case it's assumed they are a continuation of +/// an indented paragraph. /// /// {@tool snippet} /// @@ -320,8 +326,9 @@ abstract final class LicenseRegistry { return controller.stream; } - /// Resets the internal state of [LicenseRegistry]. Intended for use in - /// testing. + /// Resets the internal state of [LicenseRegistry]. + /// + /// Intended for use in testing. @visibleForTesting static void reset() { _collectors = null; diff --git a/packages/flutter/lib/src/foundation/node.dart b/packages/flutter/lib/src/foundation/node.dart index ef3a1f244c4..8b1126919bc 100644 --- a/packages/flutter/lib/src/foundation/node.dart +++ b/packages/flutter/lib/src/foundation/node.dart @@ -8,9 +8,11 @@ import 'package:meta/meta.dart'; // during device lab performance tests. When editing this file, check to make sure // that it didn't break that test. -/// Deprecated. Unused by the framework and will be removed in a future version -/// of Flutter. If needed, inline any required functionality of this class -/// directly in the subclass. +/// Deprecated; unused by the framework and will be removed in a future version +/// of Flutter. +/// +/// If needed, inline any required functionality of this class directly in the +/// subclass. /// /// An abstract node in a tree. /// diff --git a/packages/flutter/lib/src/foundation/print.dart b/packages/flutter/lib/src/foundation/print.dart index ecd6f1212d1..c0d55188af9 100644 --- a/packages/flutter/lib/src/foundation/print.dart +++ b/packages/flutter/lib/src/foundation/print.dart @@ -49,6 +49,7 @@ typedef DebugPrintCallback = void Function(String? message, {int? wrapWidth}); DebugPrintCallback debugPrint = debugPrintThrottled; /// Alternative implementation of [debugPrint] that does not throttle. +/// /// Used by tests. void debugPrintSynchronously(String? message, {int? wrapWidth}) { if (message != null && wrapWidth != null) { @@ -63,8 +64,9 @@ void debugPrintSynchronously(String? message, {int? wrapWidth}) { } } -/// Implementation of [debugPrint] that throttles messages. This avoids dropping -/// messages on platforms that rate-limit their logging (for example, Android). +/// Implementation of [debugPrint] that throttles messages. +/// +/// This avoids dropping messages on platforms that rate-limit their logging (for example, Android). /// /// If `wrapWidth` is not null, the message is wrapped using [debugWordWrap]. void debugPrintThrottled(String? message, {int? wrapWidth}) { diff --git a/packages/flutter/lib/src/foundation/serialization.dart b/packages/flutter/lib/src/foundation/serialization.dart index addc0a92468..3fed1a9d448 100644 --- a/packages/flutter/lib/src/foundation/serialization.dart +++ b/packages/flutter/lib/src/foundation/serialization.dart @@ -16,6 +16,7 @@ export 'dart:typed_data' /// The byte order used is [Endian.host] throughout. class WriteBuffer { /// Creates an interface for incrementally building a [ByteData] instance. + /// /// [startCapacity] determines the start size of the [WriteBuffer] in bytes. /// The closer that value is to the real size used, the better the /// performance. @@ -246,7 +247,7 @@ class ReadBuffer { return list; } - /// Reads the given number of Float32s from the buffer + /// Reads the given number of Float32s from the buffer. Float32List getFloat32List(int length) { _alignTo(4); final Float32List list = data.buffer.asFloat32List(data.offsetInBytes + _position, length); diff --git a/packages/flutter/lib/src/foundation/timeline.dart b/packages/flutter/lib/src/foundation/timeline.dart index 491f76bec8d..53b48ebb222 100644 --- a/packages/flutter/lib/src/foundation/timeline.dart +++ b/packages/flutter/lib/src/foundation/timeline.dart @@ -87,8 +87,9 @@ abstract final class FlutterTimeline { Timeline.instantSync(name, arguments: arguments); } - /// A utility method to time a synchronous `function`. Internally calls - /// `function` bracketed by calls to [startSync] and [finishSync]. + /// A utility method to time a synchronous `function`. + /// + /// Internally calls `function` bracketed by calls to [startSync] and [finishSync]. /// /// This is a drop-in replacement for [Timeline.timeSync]. static T timeSync( diff --git a/packages/flutter/lib/src/foundation/unicode.dart b/packages/flutter/lib/src/foundation/unicode.dart index bbfdfafa1f7..39cb298b5bd 100644 --- a/packages/flutter/lib/src/foundation/unicode.dart +++ b/packages/flutter/lib/src/foundation/unicode.dart @@ -11,26 +11,26 @@ /// * , which describes the Unicode /// bidirectional text algorithm. abstract final class Unicode { - /// `U+202A LEFT-TO-RIGHT EMBEDDING` + /// The `U+202A LEFT-TO-RIGHT EMBEDDING` character. /// /// Treat the following text as embedded left-to-right. /// /// Use [PDF] to end the embedding. static const String LRE = '\u202A'; - /// `U+202B RIGHT-TO-LEFT EMBEDDING` + /// The `U+202B RIGHT-TO-LEFT EMBEDDING` character. /// /// Treat the following text as embedded right-to-left. /// /// Use [PDF] to end the embedding. static const String RLE = '\u202B'; - /// `U+202C POP DIRECTIONAL FORMATTING` + /// The `U+202C POP DIRECTIONAL FORMATTING` character. /// /// End the scope of the last [LRE], [RLE], [RLO], or [LRO]. static const String PDF = '\u202C'; - /// `U+202A LEFT-TO-RIGHT OVERRIDE` + /// The `U+202D LEFT-TO-RIGHT OVERRIDE` character. /// /// Force following characters to be treated as strong left-to-right characters. /// @@ -39,7 +39,7 @@ abstract final class Unicode { /// Use [PDF] to end the override. static const String LRO = '\u202D'; - /// `U+202B RIGHT-TO-LEFT OVERRIDE` + /// The `U+202E RIGHT-TO-LEFT OVERRIDE` character. /// /// Force following characters to be treated as strong right-to-left characters. /// @@ -48,21 +48,21 @@ abstract final class Unicode { /// Use [PDF] to end the override. static const String RLO = '\u202E'; - /// `U+2066 LEFT-TO-RIGHT ISOLATE` + /// The `U+2066 LEFT-TO-RIGHT ISOLATE` character. /// /// Treat the following text as isolated and left-to-right. /// /// Use [PDI] to end the isolated scope. static const String LRI = '\u2066'; - /// `U+2067 RIGHT-TO-LEFT ISOLATE` + /// The `U+2067 RIGHT-TO-LEFT ISOLATE` character. /// /// Treat the following text as isolated and right-to-left. /// /// Use [PDI] to end the isolated scope. static const String RLI = '\u2067'; - /// `U+2068 FIRST STRONG ISOLATE` + /// The `U+2068 FIRST STRONG ISOLATE` character. /// /// Treat the following text as isolated and in the direction of its first /// strong directional character that is not inside a nested isolate. @@ -75,22 +75,22 @@ abstract final class Unicode { /// Use [PDI] to end the isolated scope. static const String FSI = '\u2068'; - /// `U+2069 POP DIRECTIONAL ISOLATE` + /// The `U+2069 POP DIRECTIONAL ISOLATE` character. /// /// End the scope of the last [LRI], [RLI], or [FSI]. static const String PDI = '\u2069'; - /// `U+200E LEFT-TO-RIGHT MARK` + /// The `U+200E LEFT-TO-RIGHT MARK` character. /// /// Left-to-right zero-width character. static const String LRM = '\u200E'; - /// `U+200F RIGHT-TO-LEFT MARK` + /// The `U+200F RIGHT-TO-LEFT MARK` character. /// /// Right-to-left zero-width non-Arabic character. static const String RLM = '\u200F'; - /// `U+061C ARABIC LETTER MARK` + /// The `U+061C ARABIC LETTER MARK` character. /// /// Right-to-left zero-width Arabic character. static const String ALM = '\u061C';