DEV/flutter_flutter
1
0
Fork 0
mirror of https://github.com/flutter/flutter.git synced 2026-02-20 02:29:02 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update doc in foundation to match the style guide (#181972)

Browse Source 
<!--
Thanks for filing a pull request!
Reviewers are typically assigned within a week of filing a request.
To learn more about code review, see our documentation on Tree Hygiene:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
-->

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.

<!-- Links -->
[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>
This commit is contained in:
chunhtai 2026-02-06 13:04:07 -08:00 committed by GitHub
parent 945ee8c77c
commit 4c19c37beb
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
13 changed files with 84 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
packages/flutter/lib/src/foundation/_capabilities_web.dart
View File

@ -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;

26
packages/flutter/lib/src/foundation/assertions.dart
View File

@ -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<DiagnosticPropertiesTransformer> propertiesTransformers =
<DiagnosticPropertiesTransformer>[];
/// 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

4
packages/flutter/lib/src/foundation/basic_types.dart
View File

@ -106,7 +106,9 @@ typedef AsyncValueGetter<T> = Future<T> Function();
/// returned by `where`.
class CachingIterable<E> extends IterableBase<E> {
/// 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

9
packages/flutter/lib/src/foundation/binding.dart
View File

@ -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

1
packages/flutter/lib/src/foundation/bitfield.dart
View File

@ -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.

21
packages/flutter/lib/src/foundation/change_notifier.dart
View File

@ -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<T> 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.
///

6
packages/flutter/lib/src/foundation/key.dart
View File

@ -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<T> 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

29
packages/flutter/lib/src/foundation/licenses.dart
View File

@ -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<String> 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<LicenseParagraph> 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;

8
packages/flutter/lib/src/foundation/node.dart
View File

@ -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.
///

6
packages/flutter/lib/src/foundation/print.dart
View File

@ -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}) {

3
packages/flutter/lib/src/foundation/serialization.dart
View File

@ -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);

5
packages/flutter/lib/src/foundation/timeline.dart
View File

@ -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<T>(

24
packages/flutter/lib/src/foundation/unicode.dart
View File

@ -11,26 +11,26 @@
/// * <http://unicode.org/reports/tr9/>, 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';