diff --git a/lib/ui/annotations.dart b/lib/ui/annotations.dart index 6722ba40070fe..5f7670d2fd5db 100644 --- a/lib/ui/annotations.dart +++ b/lib/ui/annotations.dart @@ -4,20 +4,20 @@ part of dart.ui; -// TODO(dnfield): Update this if/when we default this to on in the tool, -// see: https://github.com/flutter/flutter/issues/52759 -/// Annotation used by Flutter's Dart compiler to indicate that an -/// [Object.toString] override should not be replaced with a supercall. -/// -/// Since `dart:ui` and `package:flutter` override `toString` purely for -/// debugging purposes, the frontend compiler is instructed to replace all -/// `toString` bodies with `return super.toString()` during compilation. This -/// significantly reduces release code size, and would make it impossible to -/// implement a meaningful override of `toString` for release mode without -/// disabling the feature and losing the size savings. If a package uses this -/// feature and has some unavoidable need to keep the `toString` implementation -/// for a specific class, applying this annotation will direct the compiler -/// to leave the method body as-is. +/// Annotation to keep [Object.toString] overrides as-is instead of removing +/// them for size optimization purposes. +/// +/// For certain uris (currently `dart:ui` and `package:flutter`) the Dart +/// compiler will remove [Object.toString] overrides from classes in +/// profile/release mode to reduce code size. +/// +/// Individual classes can opt out of this behavior via the following +/// annotations: +/// +/// * `@pragma('flutter:keep-to-string')` +/// * `@pragma('flutter:keep-to-string-in-subtypes')` +/// +/// See https://github.com/dart-lang/sdk/blob/main/runtime/docs/pragmas.md /// /// For example, in the following class the `toString` method will remain as /// `return _buffer.toString();`, even if the `--delete-tostring-package-uri` diff --git a/lib/web_ui/lib/annotations.dart b/lib/web_ui/lib/annotations.dart index 3dbd5823e060d..f66945a667d75 100644 --- a/lib/web_ui/lib/annotations.dart +++ b/lib/web_ui/lib/annotations.dart @@ -2,14 +2,39 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. -// TODO(dnfield): Remove unused_import ignores when https://github.com/dart-lang/sdk/issues/35164 is resolved. - part of ui; -// TODO(dnfield): Update this if/when we default this to on in the tool, -// see: https://github.com/flutter/flutter/issues/52759 -const _KeepToString keepToString = _KeepToString(); - -class _KeepToString { - const _KeepToString(); -} +/// Annotation to keep [Object.toString] overrides as-is instead of removing +/// them for size optimization purposes. +/// +/// For certain uris (currently `dart:ui` and `package:flutter`) the Dart +/// compiler may remove [Object.toString] overrides from classes in +/// profile/release mode to reduce code size. +/// +/// Individual classes can opt out of this behavior via the following +/// annotations: +/// +/// * `@pragma('flutter:keep-to-string')` +/// * `@pragma('flutter:keep-to-string-in-subtypes')` +/// +/// See https://github.com/dart-lang/sdk/blob/main/runtime/docs/pragmas.md +/// +/// For example, in the following class the `toString` method will remain as +/// `return _buffer.toString();`, even if the `--delete-tostring-package-uri` +/// option would otherwise apply and replace it with `return super.toString()`. +/// (By convention, `dart:ui` is usually imported `as ui`, hence the prefix.) +/// +/// ```dart +/// class MyStringBuffer { +/// final StringBuffer _buffer = StringBuffer(); +/// +/// // ... +/// +/// @ui.keepToString +/// @override +/// String toString() { +/// return _buffer.toString(); +/// } +/// } +/// ``` +const pragma keepToString = pragma('flutter:keep-to-string'); diff --git a/lib/web_ui/lib/platform_dispatcher.dart b/lib/web_ui/lib/platform_dispatcher.dart index 9b91935beb4ff..9180ef6b22869 100644 --- a/lib/web_ui/lib/platform_dispatcher.dart +++ b/lib/web_ui/lib/platform_dispatcher.dart @@ -502,6 +502,7 @@ class Locale { @override int get hashCode => Object.hash(languageCode, scriptCode, countryCode); + @keepToString @override String toString() => _rawToString('_');