📝 Update doc (#913)

Author: CaiJingLong

lib/src/filter/base_filter.dart

@@ -1,3 +1,7 @@
+// Copyright 2018 The FlutterCandies author. All rights reserved.
+// Use of this source code is governed by an Apache license that can be found
+// in the LICENSE file.
+
 import 'custom/custom_columns.dart';
 import 'custom/custom_filter.dart';
 import 'custom/order_by_item.dart';
@@ -48,7 +52,7 @@ abstract class PMFilter {
 
   /// Whether the [AssetPathEntity]s will return with modified time.
   ///
-  /// This option is performance-consuming. Use with cautious.
+  /// This option is performance-consuming. Use with caution.
   ///
   /// See also:
   ///  * [AssetPathEntity.lastModified].
@@ -62,7 +66,7 @@ abstract class PMFilter {
   /// The subclass should override this method to make params.
   Map<String, dynamic> childMap();
 
-  /// The method only support for [FilterOptionGroup].
+  /// The method only supports for [FilterOptionGroup].
   PMFilter updateDateToNow();
 
   /// Convert the filter to a map for channel.

lib/src/filter/classical/filter_option_group.dart

@@ -8,9 +8,31 @@ import '../../internal/enums.dart';
 import '../base_filter.dart';
 import 'filter_options.dart';
 
-/// The group class to obtain [FilterOption]s.
+/// A collection of filtering and sorting options for querying assets.
+///
+/// Use this class to specify how to filter and sort a set of assets returned by [PhotoManager].
+///
+/// The [FilterOptionGroup] object contains several [FilterOption] objects, one for each type of asset (image, video, audio).
+/// You can set specific filtering and sorting options for each type of asset using the corresponding [FilterOption] object.
+///
+/// Additionally, you can specify whether to include modified path results, whether to include live photos,
+/// or whether to only include live photos, using the appropriate properties of this object.
+///
+/// Finally, you can use the [orders] property to specify sorting options for the results.
 class FilterOptionGroup extends PMFilter {
   /// Construct a default options group.
+  ///
+  /// Parameters:
+  ///
+  /// * `imageOption`: The option for filtering image assets. Defaults to [FilterOption].
+  /// * `videoOption`: The option for filtering video assets. Defaults to [FilterOption].
+  /// * `audioOption`: The option for filtering audio assets. Defaults to [FilterOption].
+  /// * `containsPathModified`: Whether the result should contain assets whose file path has been modified. Defaults to `false`.
+  /// * `containsLivePhotos`: Whether the result should contain live photos. This option only takes effects on iOS. Defaults to `true`.
+  /// * `onlyLivePhotos`: Whether the result should only contain live photos. This option only takes effects on iOS and when the request type is image. Defaults to `false`.
+  /// * `createTimeCond`: The condition for filtering asset creation time. See [DateTimeCond] for more information. Defaults to `DateTimeCond.def()`.
+  /// * `updateTimeCond`: The condition for filtering asset update time. See [DateTimeCond] for more information. By default, this option is ignored.
+  /// * `orders`: A list of options for sorting the results. Defaults to an empty list.
   FilterOptionGroup({
     FilterOption imageOption = const FilterOption(),
     FilterOption videoOption = const FilterOption(),
@@ -32,37 +54,78 @@ class FilterOptionGroup extends PMFilter {
   }
 
   /// Construct an empty options group.
+  ///
+  /// Returns a new [FilterOptionGroup] instance with default options for all asset types and no other filters applied.
   FilterOptionGroup.empty();
 
   /// Whether to obtain only live photos.
   ///
   /// This option only takes effects on iOS and when the request type is image.
   bool onlyLivePhotos = false;
 
-  /// Whether to obtain live photos.
+  /// Whether the result should contain live photos.
+  ///
+  /// Defaults to `true`.
   ///
   /// This option only takes effects on iOS.
   bool containsLivePhotos = true;
 
   final Map<AssetType, FilterOption> _map = <AssetType, FilterOption>{};
 
-  /// Get the [FilterOption] according the specific [AssetType].
+  /// Get the [FilterOption] object for the specified [AssetType].
+  ///
+  /// Parameters:
+  ///
+  /// * `type`: The type of asset.
+  ///
+  /// Returns the [FilterOption] object associated with the specified [AssetType].
   FilterOption getOption(AssetType type) => _map[type]!;
 
-  /// Set the [FilterOption] according the specific [AssetType].
+  /// Set the [FilterOption] object for the specified [AssetType].
+  ///
+  /// Parameters:
+  ///
+  /// * `type`: The type of asset to set the [FilterOption] for.
+  /// * `option`: The new [FilterOption] to set.
   void setOption(AssetType type, FilterOption option) {
     _map[type] = option;
   }
 
+  /// The condition for filtering asset creation time.
+  ///
+  /// Defaults to `DateTimeCond.def()`.
+  ///
+  /// See [DateTimeCond] for more information on how to specify date and time conditions.
   DateTimeCond createTimeCond = DateTimeCond.def();
+
+  /// The condition for filtering asset update time.
+  ///
+  /// By default, this option is ignored.
+  ///
+  /// See [DateTimeCond] for more information on how to specify date and time conditions.
   DateTimeCond updateTimeCond = DateTimeCond.def().copyWith(ignore: true);
 
+  /// A list of options for sorting the results.
+  ///
+  /// By default, the order is not specified.
+  ///
+  /// See [OrderOption] for more information on how to specify sorting options.
   final List<OrderOption> orders = <OrderOption>[];
 
+  /// Adds an [OrderOption] to the list of sorting options.
+  ///
+  /// Parameters:
+  ///
+  /// * `option`: The [OrderOption] to add to the list.
   void addOrderOption(OrderOption option) {
     orders.add(option);
   }
 
+  /// Merges another [FilterOptionGroup] into this one.
+  ///
+  /// Parameters:
+  ///
+  /// * `other`: The [FilterOptionGroup] to merge into this one.
   void merge(FilterOptionGroup other) {
     for (final AssetType type in _map.keys) {
       _map[type] = _map[type]!.merge(other.getOption(type));
@@ -106,6 +169,21 @@ class FilterOptionGroup extends PMFilter {
     };
   }
 
+  /// Returns a new [FilterOptionGroup] with the same options as this one, but with some options replaced.
+  ///
+  /// Parameters:
+  ///
+  /// * `imageOption`: New image filter option. Defaults to the current object's option.
+  /// * `videoOption`: New video filter option. Defaults to the current object's option.
+  /// * `audioOption`: New audio filter option. Defaults to the current object's option.
+  /// * `containsPathModified`: Whether to include results with modified paths. Defaults to the same as the current object.
+  /// * `containsLivePhotos`: Whether to include live photos. Defaults to the same as the current object.
+  /// * `onlyLivePhotos`: Whether to include only live photos. Defaults to the same as the current object.
+  /// * `createTimeCond`: Date and time conditions for filtering creation time. Defaults to the same as the current object.
+  /// * `updateTimeCond`: Date and time conditions for filtering update time. Defaults to the same as the current object.
+  /// * `orders`: Sorting options for the results. Defaults to the same as the current object.
+  ///
+  /// Returns a new [FilterOptionGroup] object with the specified options.
   FilterOptionGroup copyWith({
     FilterOption? imageOption,
     FilterOption? videoOption,