Improve CupertinoDatePicker docs (#57534)

packages/flutter/lib/src/cupertino/date_picker.dart

@@ -211,15 +211,17 @@ class CupertinoDatePicker extends StatefulWidget {
   /// the intervals set in [minimumDate], [maximumDate], [minimumYear], and
   /// [maximumYear].
   ///
-  /// [minimumDate] is the minimum [DateTime] that the picker can be scrolled to.
-  /// Null if there's no limit. In [CupertinoDatePickerMode.time] mode, if the
-  /// date part of [initialDateTime] is after that of the [minimumDate], [minimumDate]
-  /// has no effect.
+  /// [minimumDate] is the minimum selectable [DateTime] of the picker. When set
+  /// to null, the picker does not limit the minimum [DateTime] the user can pick.
+  /// In [CupertinoDatePickerMode.time] mode, [minimumDate] should typically be
+  /// on the same date as [initialDateTime], as the picker will not limit the
+  /// minimum time the user can pick if it's set to a date earlier than that.
   ///
-  /// [maximumDate] is the maximum [DateTime] that the picker can be scrolled to.
-  /// Null if there's no limit. In [CupertinoDatePickerMode.time] mode, if the
-  /// date part of [initialDateTime] is before that of the [maximumDate], [maximumDate]
-  /// has no effect.
+  /// [maximumDate] is the maximum selectable [DateTime] of the picker. When set
+  /// to null, the picker does not limit the maximum [DateTime] the user can pick.
+  /// In [CupertinoDatePickerMode.time] mode, [maximumDate] should typically be
+  /// on the same date as [initialDateTime], as the picker will not limit the
+  /// maximum time the user can pick if it's set to a date later than that.
   ///
   /// [minimumYear] is the minimum year that the picker can be scrolled to in
   /// [CupertinoDatePickerMode.date] mode. Defaults to 1 and must not be null.
@@ -296,12 +298,34 @@ class CupertinoDatePicker extends StatefulWidget {
   /// selected date time.
   final DateTime initialDateTime;
 
-  /// Minimum date that the picker can be scrolled to in [CupertinoDatePickerMode.date]
-  /// and [CupertinoDatePickerMode.dateAndTime] mode. Null if there's no limit.
+  /// The minimum selectable date that the picker can settle on.
+  ///
+  /// When non-null, the user can still scroll the picker to [DateTime]s earlier
+  /// than [minimumDate], but the [onDateChangeCallback] will not be called on
+  /// these [DateTime]s. Once let go, the picker will scroll back to [minimumDate].
+  ///
+  /// In [CupertinoDatePickerMode.time] mode, a time becomes unselectable if the
+  /// [DateTime] produced by combining that particular time and the date part of
+  /// [initialDateTime] is earlier than [minimumDate]. So typically [minimumDate]
+  /// needs to be set to a [DateTime] that is on the same date as [initialDateTime].
+  ///
+  /// Defaults to null. When set to null, the picker does not impose a limit on
+  /// the earliest [DateTime] the user can select.
   final DateTime minimumDate;
 
-  /// Maximum date that the picker can be scrolled to in [CupertinoDatePickerMode.date]
-  /// and [CupertinoDatePickerMode.dateAndTime] mode. Null if there's no limit.
+  /// The maximum selectable date that the picker can settle on.
+  ///
+  /// When non-null, the user can still scroll the picker to [DateTime]s later
+  /// than [maximumDate], but the [onDateChangeCallback] will not be called on
+  /// these [DateTime]s. Once let go, the picker will scroll back to [maximumDate].
+  ///
+  /// In [CupertinoDatePickerMode.time] mode, a time becomes unselectable if the
+  /// [DateTime] produced by combining that particular time and the date part of
+  /// [initialDateTime] is later than [maximumDate]. So typically [maximumDate]
+  /// needs to be set to a [DateTime] that is on the same date as [initialDateTime].
+  ///
+  /// Defaults to null. When set to null, the picker does not impose a limit on
+  /// the latest [DateTime] the user can select.
   final DateTime maximumDate;
 
   /// Minimum year that the picker can be scrolled to in
@@ -319,9 +343,9 @@ class CupertinoDatePicker extends StatefulWidget {
   /// Whether to use 24 hour format. Defaults to false.
   final bool use24hFormat;
 
-  /// Callback called when the selected date and/or time changes. If the new selected
-  /// [DateTime] is not valid, or is not in the [minimumDate] through [maximumDate]
-  /// range, this callback will not be called.
+  /// Callback called when the selected date and/or time changes. If the new
+  /// selected [DateTime] is not valid, or is not in the [minimumDate] through
+  /// [maximumDate] range, this callback will not be called.
   ///
   /// Must not be null.
   final ValueChanged<DateTime> onDateTimeChanged;