dart_doc

Please add comprehensive Dart documentation comments to the specified classes, following these guidelines:

1. Always focus on WHY (key Design Decisions) it does what it does in concise manner.
2. Use /// for documentation comments.
3. Start with a brief, single-sentence summary of the class's purpose.
4. Follow with a more detailed description if necessary, keeping it concise.
5. Include an @ai annotation with specific instructions for AI tools on how to interpret and use this class.
6. Document all public members (methods, properties, etc.) with clear, concise explanations of their purpose and usage.
7. Use [bracketed] references for any mentioned identifiers within the class.
8. Include code examples where appropriate, using ```dart code fences.
9. Mention any important relationships with other classes or libraries.
10. Use PREFER, AVOID, or CONSIDER for recommendations about usage patterns.
11. Add @deprecated tags with explanations for any deprecated members.
12. Place doc comments before metadata annotations.
13. Use prose to explain parameters, return values, and exceptions.
14. For boolean properties, start comments with "Whether" followed by a description.
15. Document only the getter for properties with both a getter and setter.
16. Consider including a code sample in the class-level comment.
17. Keep 80-length characters per line.

Example format:

/// {@template progress_indicator}
/// A widget that displays a customizable progress indicator.
///
/// This class provides a flexible way to show loading progress in your app.
/// It supports both determinate and indeterminate progress modes.
///
/// Use [ProgressIndicator.circular] for a circular indicator, or
/// [ProgressIndicator.linear] for a linear one.
///
/// ```dart
/// ProgressIndicator(
///   value: 0.7,
///   backgroundColor: Colors.grey[300],
///   valueColor: AlwaysStoppedAnimation<Color>(Colors.blue),
/// )
/// ```
///
/// See also:
///
///  * [CircularProgressIndicator], which shows progress along a circular arc.
///  * [LinearProgressIndicator], which displays progress along a line.
///
/// @ai When generating code involving this class, ensure proper initialization
/// of [value] and consider the appropriate use of [backgroundColor] and [valueColor].
/// {@endtemplate}
class ProgressIndicator extends StatefulWidget {
  /// {@macro progress_indicator}
  ///
  /// Creates a progress indicator.
  ///
  /// The [value] argument should be null for an indeterminate progress indicator.
  /// For determinate progress indicators, [value] should be a non-null value
  /// between 0.0 and 1.0, inclusive.
  ///
  /// @ai Ensure [value] is within the valid range when provided.
  const ProgressIndicator({
    Key? key,
    this.value,
    this.backgroundColor,
    this.valueColor,
    this.semanticsLabel,
    this.semanticsValue,
  }) : super(key: key);

  /// The progress value between 0.0 and 1.0.
  ///
  /// If null, the progress indicator is indeterminate.
  ///
  /// @ai Use this property to control the progress. Ensure it's between 0.0 and 1.0.
  final double? value;

  /// The progress indicator's background color.
  ///
  /// @ai Consider using a contrasting color to [valueColor] for better visibility.
  final Color? backgroundColor;

  /// The progress indicator's color as an animated value.
  ///
  /// @ai Use [AlwaysStoppedAnimation] for a solid color, or custom animations for dynamic effects.
  final Animation<Color?>? valueColor;

  /// Creates a circular progress indicator.
  ///
  /// @ai Use this constructor for a circular representation of progress.
  const ProgressIndicator.circular({Key? key}) : this(key: key);

  /// Creates a linear progress indicator.
  ///
  /// @ai Use this constructor for a linear representation of progress.
  const ProgressIndicator.linear({Key? key}) : this(key: key);

  /// This method is deprecated and will be removed in the next major version.
  ///
  /// Use [newMethod] instead.
  @Deprecated('Use newMethod() instead')
  void oldMethod() {
    // ...
  }

  @override
  State<ProgressIndicator> createState() => _ProgressIndicatorState();
}