Remove 'must be non-null' and 'must not be null' comments from non-framework libraries (#134994)

## Description This removes all of the comments that are of the form "so-and-so must not be null" or "so-and-so must be non-null" from the cases where those values are defines as non-nullable values. This PR removes them from the library in the repo that don't have anything to do with the framework. This was done by hand, since it really didn't lend itself to scripting, so it needs to be more than just spot-checked, I think. I was careful to leave any comment that referred to parameters that were nullable, but I may have missed some. In addition to being no longer relevant after null safety has been made the default, these comments were largely fragile, in that it was easy for them to get out of date, and not be accurate anymore anyhow. This did create a number of constructor comments which basically say "Creates a [Foo].", but I don't really know how to avoid that in a large scale change, since there's not much you can really say in a lot of cases. I think we might consider some leniency for constructors to the "Comment must be meaningful" style guidance (which we de facto have already, since there are a bunch of these). ## Related PRs - https://github.com/flutter/flutter/pull/134984 - https://github.com/flutter/flutter/pull/134991 - https://github.com/flutter/flutter/pull/134992 - https://github.com/flutter/flutter/pull/134993 ## Tests - Documentation only change.
2024-08-25 11:07:06 +00:00 · 2023-09-19 10:26:07 -07:00 · 2023-09-19 10:26:07 -07:00 · 4ce7fdd92b
parent d3c60569d1
commit 4ce7fdd92b
12 changed files with 7 additions and 60 deletions
--- a/dev/benchmarks/macrobenchmarks/lib/src/web/recorder.dart
+++ b/dev/benchmarks/macrobenchmarks/lib/src/web/recorder.dart
@ -83,8 +83,6 @@ Future<void> _dummyAsyncVoidCallback() async {}
@sealed
 class Runner {
  /// Creates a runner for the [recorder].
-  ///
-  /// All arguments must not be null.
  Runner({
    required this.recorder,
    this.setUpAllDidRun = _dummyAsyncVoidCallback,
--- a/dev/tools/gen_keycodes/lib/physical_key_data.dart
+++ b/dev/tools/gen_keycodes/lib/physical_key_data.dart
@ -214,8 +214,6 @@ class PhysicalKeyData {
 /// written with the [toJson] method.
 class PhysicalKeyEntry {
  /// Creates a single key entry from available data.
-  ///
-  /// The [usbHidCode] and [chromiumName] parameters must not be null.
  PhysicalKeyEntry({
    required this.usbHidCode,
    required this.name,
--- a/examples/layers/rendering/src/sector_layout.dart
+++ b/examples/layers/rendering/src/sector_layout.dart
@ -636,8 +636,6 @@ class SectorHitTestResult extends HitTestResult {
 /// A hit test entry used by [RenderSector].
 class SectorHitTestEntry extends HitTestEntry {
  /// Creates a box hit test entry.
-  ///
-  /// The [radius] and [theta] argument must not be null.
  SectorHitTestEntry(RenderSector super.target, { required this.radius,  required this.theta });

  @override
--- a/packages/flutter_driver/lib/src/common/wait.dart
+++ b/packages/flutter_driver/lib/src/common/wait.dart
@ -9,8 +9,6 @@ import 'message.dart';
 /// A Flutter Driver command that waits until a given [condition] is satisfied.
 class WaitForCondition extends Command {
  /// Creates a command that waits for the given [condition] is met.
-  ///
-  /// The [condition] argument must not be null.
  const WaitForCondition(this.condition, {super.timeout});

  /// Deserializes this command from the value generated by [serialize].
@ -89,8 +87,6 @@ class NoTransientCallbacks extends SerializableWaitCondition {

  /// Factory constructor to parse a [NoTransientCallbacks] instance from the
  /// given JSON map.
-  ///
-  /// The [json] argument must not be null.
  factory NoTransientCallbacks.deserialize(Map<String, String> json) {
    if (json['conditionName'] != 'NoTransientCallbacksCondition') {
      throw SerializationException('Error occurred during deserializing the NoTransientCallbacksCondition JSON string: $json');
@ -109,8 +105,6 @@ class NoPendingFrame extends SerializableWaitCondition {

  /// Factory constructor to parse a [NoPendingFrame] instance from the given
  /// JSON map.
-  ///
-  /// The [json] argument must not be null.
  factory NoPendingFrame.deserialize(Map<String, String> json) {
    if (json['conditionName'] != 'NoPendingFrameCondition') {
      throw SerializationException('Error occurred during deserializing the NoPendingFrameCondition JSON string: $json');
@ -129,8 +123,6 @@ class FirstFrameRasterized extends SerializableWaitCondition {

  /// Factory constructor to parse a [FirstFrameRasterized] instance from the
  /// given JSON map.
-  ///
-  /// The [json] argument must not be null.
  factory FirstFrameRasterized.deserialize(Map<String, String> json) {
    if (json['conditionName'] != 'FirstFrameRasterizedCondition') {
      throw SerializationException('Error occurred during deserializing the FirstFrameRasterizedCondition JSON string: $json');
@ -152,8 +144,6 @@ class NoPendingPlatformMessages extends SerializableWaitCondition {

  /// Factory constructor to parse a [NoPendingPlatformMessages] instance from the
  /// given JSON map.
-  ///
-  /// The [json] argument must not be null.
  factory NoPendingPlatformMessages.deserialize(Map<String, String> json) {
    if (json['conditionName'] != 'NoPendingPlatformMessagesCondition') {
      throw SerializationException('Error occurred during deserializing the NoPendingPlatformMessagesCondition JSON string: $json');
@ -168,14 +158,10 @@ class NoPendingPlatformMessages extends SerializableWaitCondition {
 /// A combined condition that waits until all the given [conditions] are met.
 class CombinedCondition extends SerializableWaitCondition {
  /// Creates a [CombinedCondition] condition.
-  ///
-  /// The [conditions] argument must not be null.
  const CombinedCondition(this.conditions);

  /// Factory constructor to parse a [CombinedCondition] instance from the
  /// given JSON map.
-  ///
-  /// The [jsonMap] argument must not be null.
  factory CombinedCondition.deserialize(Map<String, String> jsonMap) {
    if (jsonMap['conditionName'] != 'CombinedCondition') {
      throw SerializationException('Error occurred during deserializing the CombinedCondition JSON string: $jsonMap');
@ -210,8 +196,6 @@ class CombinedCondition extends SerializableWaitCondition {
 }

 /// Parses a [SerializableWaitCondition] or its subclass from the given [json] map.
-///
-/// The [json] argument must not be null.
 SerializableWaitCondition _deserialize(Map<String, String> json) {
  final String conditionName = json['conditionName']!;
  switch (conditionName) {
--- a/packages/flutter_driver/lib/src/extension/wait_conditions.dart
+++ b/packages/flutter_driver/lib/src/extension/wait_conditions.dart
@ -39,8 +39,6 @@ class _InternalNoTransientCallbacksCondition implements WaitCondition {

  /// Factory constructor to parse an [InternalNoTransientCallbacksCondition]
  /// instance from the given [SerializableWaitCondition] instance.
-  ///
-  /// The [condition] argument must not be null.
  factory _InternalNoTransientCallbacksCondition.deserialize(SerializableWaitCondition condition) {
    if (condition.conditionName != 'NoTransientCallbacksCondition') {
      throw SerializationException('Error occurred during deserializing from the given condition: ${condition.serialize()}');
@ -67,8 +65,6 @@ class _InternalNoPendingFrameCondition implements WaitCondition {

  /// Factory constructor to parse an [InternalNoPendingFrameCondition] instance
  /// from the given [SerializableWaitCondition] instance.
-  ///
-  /// The [condition] argument must not be null.
  factory _InternalNoPendingFrameCondition.deserialize(SerializableWaitCondition condition) {
    if (condition.conditionName != 'NoPendingFrameCondition') {
      throw SerializationException('Error occurred during deserializing from the given condition: ${condition.serialize()}');
@ -95,8 +91,6 @@ class _InternalFirstFrameRasterizedCondition implements WaitCondition {

  /// Factory constructor to parse an [InternalNoPendingFrameCondition] instance
  /// from the given [SerializableWaitCondition] instance.
-  ///
-  /// The [condition] argument must not be null.
  factory _InternalFirstFrameRasterizedCondition.deserialize(SerializableWaitCondition condition) {
    if (condition.conditionName != 'FirstFrameRasterizedCondition') {
      throw SerializationException('Error occurred during deserializing from the given condition: ${condition.serialize()}');
@ -121,8 +115,6 @@ class _InternalNoPendingPlatformMessagesCondition implements WaitCondition {

  /// Factory constructor to parse an [_InternalNoPendingPlatformMessagesCondition] instance
  /// from the given [SerializableWaitCondition] instance.
-  ///
-  /// The [condition] argument must not be null.
  factory _InternalNoPendingPlatformMessagesCondition.deserialize(SerializableWaitCondition condition) {
    if (condition.conditionName != 'NoPendingPlatformMessagesCondition') {
      throw SerializationException('Error occurred during deserializing from the given condition: ${condition.serialize()}');
@ -150,14 +142,10 @@ class _InternalNoPendingPlatformMessagesCondition implements WaitCondition {
 class _InternalCombinedCondition implements WaitCondition {
  /// Creates an [_InternalCombinedCondition] instance with the given list of
  /// [conditions].
-  ///
-  /// The [conditions] argument must not be null.
  const _InternalCombinedCondition(this.conditions);

  /// Factory constructor to parse an [_InternalCombinedCondition] instance from
  /// the given [SerializableWaitCondition] instance.
-  ///
-  /// The [condition] argument must not be null.
  factory _InternalCombinedCondition.deserialize(SerializableWaitCondition condition) {
    if (condition.conditionName != 'CombinedCondition') {
      throw SerializationException('Error occurred during deserializing from the given condition: ${condition.serialize()}');
@ -187,8 +175,6 @@ class _InternalCombinedCondition implements WaitCondition {
 }

 /// Parses a [WaitCondition] or its subclass from the given serializable [waitCondition].
-///
-/// The [waitCondition] argument must not be null.
 WaitCondition deserializeCondition(SerializableWaitCondition waitCondition) {
  final String conditionName = waitCondition.conditionName;
  switch (conditionName) {
--- a/packages/flutter_test/lib/src/animation_sheet.dart
+++ b/packages/flutter_test/lib/src/animation_sheet.dart
@ -175,8 +175,6 @@ class AnimationSheetBuilder {
  /// [collate]. If neither condition is met, the frames are not recorded, which
  /// is useful during setup phases.
  ///
-  /// The `child` must not be null.
-  ///
  /// See also:
  ///
  ///  * [WidgetTester.pumpFrames], which renders a widget in a series of frames
--- a/packages/flutter_test/lib/src/binding.dart
+++ b/packages/flutter_test/lib/src/binding.dart
@ -782,7 +782,7 @@ abstract class TestWidgetsFlutterBinding extends BindingBase
  ///
  /// The `description` is used by the [LiveTestWidgetsFlutterBinding] to
  /// show a label on the screen during the test. The description comes from
-  /// the value passed to [testWidgets]. It must not be null.
+  /// the value passed to [testWidgets].
  Future<void> runTest(
    Future<void> Function() testBody,
    VoidCallback invariantTester, {
--- a/packages/flutter_test/lib/src/controller.dart
+++ b/packages/flutter_test/lib/src/controller.dart
@ -1426,7 +1426,7 @@ abstract class WidgetController {
  /// Specify `platform` as one of the platforms allowed in
  /// [platform.Platform.operatingSystem] to make the event appear to be from
  /// that type of system. Defaults to "web" on web, and "android" everywhere
-  /// else. Must not be null.
+  /// else.
  ///
  /// Specify the `physicalKey` for the event to override what is included in
  /// the simulated event. If not specified, it uses a default from the US
@ -1471,7 +1471,7 @@ abstract class WidgetController {
  /// Specify `platform` as one of the platforms allowed in
  /// [platform.Platform.operatingSystem] to make the event appear to be from
  /// that type of system. Defaults to "web" on web, and "android" everywhere
-  /// else. Must not be null.
+  /// else.
  ///
  /// Specify the `physicalKey` for the event to override what is included in
  /// the simulated event. If not specified, it uses a default from the US
--- a/packages/flutter_test/lib/src/test_default_binary_messenger.dart
+++ b/packages/flutter_test/lib/src/test_default_binary_messenger.dart
@ -47,8 +47,6 @@ typedef AllMessagesHandler = Future<ByteData?>? Function(
 /// Listeners for these messages are configured using [setMessageHandler].
 class TestDefaultBinaryMessenger extends BinaryMessenger {
  /// Creates a [TestDefaultBinaryMessenger] instance.
-  ///
-  /// The [delegate] instance must not be null.
  TestDefaultBinaryMessenger(
    this.delegate, {
    Map<String, MessageHandler> outboundHandlers = const <String, MessageHandler>{},
--- a/packages/flutter_tools/lib/src/build_system/targets/icon_tree_shaker.dart
+++ b/packages/flutter_tools/lib/src/build_system/targets/icon_tree_shaker.dart
@ -28,8 +28,6 @@ List<Map<String, Object?>> _getList(Object? object, String errorMessage) {
 class IconTreeShaker {
  /// Creates a wrapper for icon font subsetting.
  ///
-  /// The environment parameter must not be null.
-  ///
  /// If the `fontManifest` parameter is null, [enabled] will return false since
  /// there are no fonts to shake.
  ///
--- a/packages/flutter_tools/lib/src/ios/plist_parser.dart
+++ b/packages/flutter_tools/lib/src/ios/plist_parser.dart
@ -44,8 +44,6 @@ class PlistParser {
  ///
  /// If [plistFilePath] points to a non-existent file or a file that's not a
  /// valid property list file, this will return null.
-  ///
-  /// The [plistFilePath] argument must not be null.
  String? plistXmlContent(String plistFilePath) {
    if (!_fileSystem.isFileSync(_plutilExecutable)) {
      throw const FileNotFoundException(_plutilExecutable);
@ -101,8 +99,6 @@ class PlistParser {
  ///
  /// If [plistFilePath] points to a non-existent file or a file that's not a
  /// valid property list file, this will return an empty map.
-  ///
-  /// The [plistFilePath] argument must not be null.
  Map<String, Object> parseFile(String plistFilePath) {
    if (!_fileSystem.isFileSync(plistFilePath)) {
      return const <String, Object>{};
@ -176,8 +172,6 @@ class PlistParser {
  /// valid property list file, this will return null.
  ///
  /// If [key] is not found in the property list, this will return null.
-  ///
-  /// The [plistFilePath] and [key] arguments must not be null.
  T? getValueFromFile<T>(String plistFilePath, String key) {
    final Map<String, dynamic> parsed = parseFile(plistFilePath);
    return parsed[key] as T?;
--- a/packages/flutter_web_plugins/lib/src/plugin_event_channel.dart
+++ b/packages/flutter_web_plugins/lib/src/plugin_event_channel.dart
@ -15,10 +15,9 @@ import 'plugin_registry.dart';
 /// channel sends a stream of events to the handler listening on the
 /// framework-side.
 ///
-/// The channel [name] must not be null. If no [codec] is provided, then
-/// [StandardMethodCodec] is used. If no [binaryMessenger] is provided, then
-/// [pluginBinaryMessenger], which sends messages to the framework-side,
-/// is used.
+/// If no [codec] is provided, then [StandardMethodCodec] is used. If no
+/// [binaryMessenger] is provided, then [pluginBinaryMessenger], which sends
+/// messages to the framework-side, is used.
 ///
 /// Channels created using this class implement two methods for
 /// subscribing to the event stream. The methods use the encoding of
@ -37,8 +36,6 @@ import 'plugin_registry.dart';
 /// subscribed are silently discarded.
 class PluginEventChannel<T> {
  /// Creates a new plugin event channel.
-  ///
-  /// The [name] and [codec] arguments must not be null.
  const PluginEventChannel(
    this.name, [
    this.codec = const StandardMethodCodec(),
@ -46,13 +43,11 @@ class PluginEventChannel<T> {
  ]);

  /// The logical channel on which communication happens.
-  ///
-  /// This must not be null.
  final String name;

  /// The message codec used by this channel.
  ///
-  /// This must not be null. This defaults to [StandardMethodCodec].
+  /// Defaults to [StandardMethodCodec].
  final MethodCodec codec;

  /// The messenger used by this channel to send platform messages.