Make @keepToString annotation work for web and non-web (#51251)

* Update documentation for the annotation
* Add `@keepToString` annotation to web's `Locale` class (similar to
non-webs `Locale` class)

Issue flutter/flutter#52759

Author: mkustermann

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`

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

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('_');