From 4c19c37bebf0ce4b5ae85cd75f33e559d54f6381 Mon Sep 17 00:00:00 2001 From: chunhtai <47866232+chunhtai@users.noreply.github.com> Date: Fri, 6 Feb 2026 13:04:07 -0800 Subject: [PATCH] Update doc in foundation to match the style guide (#181972) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit doc should start with one sentence ## Pre-launch Checklist - [ ] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [ ] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [ ] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [ ] I signed the [CLA]. - [ ] I listed at least one issue that this PR fixes in the description above. - [ ] I updated/added relevant documentation (doc comments with `///`). - [ ] I added new tests to check the change I am making, or this PR is [test-exempt]. - [ ] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [ ] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md --------- Co-authored-by: Loïc Sharma <737941+loic-sharma@users.noreply.github.com> --- .../lib/src/foundation/_capabilities_web.dart | 4 +-- .../lib/src/foundation/assertions.dart | 26 +++++++++-------- .../lib/src/foundation/basic_types.dart | 4 ++- .../flutter/lib/src/foundation/binding.dart | 9 +++--- .../flutter/lib/src/foundation/bitfield.dart | 1 + .../lib/src/foundation/change_notifier.dart | 21 ++++++++------ packages/flutter/lib/src/foundation/key.dart | 6 ++-- .../flutter/lib/src/foundation/licenses.dart | 29 ++++++++++++------- packages/flutter/lib/src/foundation/node.dart | 8 +++-- .../flutter/lib/src/foundation/print.dart | 6 ++-- .../lib/src/foundation/serialization.dart | 3 +- .../flutter/lib/src/foundation/timeline.dart | 5 ++-- .../flutter/lib/src/foundation/unicode.dart | 24 +++++++-------- 13 files changed, 84 insertions(+), 62 deletions(-) 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';