💡 add DecodeOptions documentation

README.md

@@ -70,7 +70,7 @@ expect(
 );
 ```
 
-By default, when nesting `Map`s qs will only parse up to 5 children deep. This means if you attempt to parse a string 
+By default, when nesting `Map`s QS will only parse up to 5 children deep. This means if you attempt to parse a string 
 like 'a[b][c][d][e][f][g][h][i]=j' your resulting `Map` will be:
 
 ```dart
@@ -110,7 +110,7 @@ expect(
 );
 ```
 
-The depth limit helps mitigate abuse when qs is used to parse user input, and it is recommended to keep it a reasonably 
+The depth limit helps mitigate abuse when QS is used to parse user input, and it is recommended to keep it a reasonably 
 small number.
 
 For similar reasons, by default **QS** will only parse up to 1000 parameters. This can be overridden by passing 

lib/src/enums/duplicates.dart

@@ -1,4 +1,4 @@
-/// An enum of all available duplicate handling strategies.
+/// An enum of all available duplicate key handling strategies.
 enum Duplicates {
   combine,
   first,

lib/src/models/decode_options.dart

@@ -33,28 +33,87 @@ final class DecodeOptions with EquatableMixin {
           'Invalid charset',
         );
 
+  /// Set to [true] to decode dot [Map] notation in the encoded input.
   final bool allowDots;
+
+  /// Set to [true] to allow empty [List] values inside [Map]s in the encoded input.
   final bool allowEmptyLists;
+
+  /// [QS] will limit specifying indices in a [List] to a maximum index of `20`.
+  /// Any [List] members with an index of greater than `20` will instead be converted to a [Map] with the index as the key.
+  /// This is needed to handle cases when someone sent, for example, `a[999999999]` and it will take significant time to iterate
+  /// over this huge [List].
+  /// This limit can be overridden by passing an [listLimit] option.
   final int listLimit;
+
+  /// The character encoding to use when decoding the input.
   final Encoding charset;
+
+  /// Some services add an initial `utf8=✓` value to forms so that old InternetExplorer versions are more likely to submit the
+  /// form as [utf8]. Additionally, the server can check the value against wrong encodings of the checkmark character and detect
+  /// that a query string or `application/x-www-form-urlencoded` body was *not* sent as [utf8], eg. if the form had an
+  /// `accept-charset` parameter or the containing page had a different character set.
+  ///
+  /// [QS] supports this mechanism via the [charsetSentinel] option.
+  /// If specified, the [utf8] parameter will be omitted from the returned [Map].
+  /// It will be used to switch to [latin1]/[utf8] mode depending on how the checkmark is encoded.
+  ///
+  /// Important: When you specify both the [charset] option and the [charsetSentinel] option,
+  /// the [charset] will be overridden when the request contains a [utf8] parameter from which the actual charset
+  /// can be deduced. In that sense the [charset] will behave as the default charset rather than the authoritative
+  /// charset.
   final bool charsetSentinel;
+
+  /// Set to [true] to parse the input as a comma-separated value.
+  ///
+  /// Note: nested [Map]s, such as `'a={b:1},{c:d}'` are not supported.
   final bool comma;
+
+  /// Set to [true] to decode dots in keys.
+  ///
+  /// Note: it implies [allowDots], so [QS.decode] will error if you set
+  /// [decodeDotInKeys] to [true], and [allowDots] to [false].
   final bool decodeDotInKeys;
+
+  /// The delimiter to use when splitting key-value pairs in the encoded input.
+  /// Can be a [String] or a [RegExp].
   final Pattern delimiter;
+
+  /// By default, when nesting [Map]s [QS] will only decode up to 5 children deep.
+  /// This depth can be overridden by setting the [depth].
+  /// The depth limit helps mitigate abuse when qs is used to parse user input,
+  /// and it is recommended to keep it a reasonably small number.
   final int depth;
+
+  /// For similar reasons, by default [QS] will only parse up to 1000
+  /// parameters. This can be overridden by passing a [parameterLimit]
+  /// option.
+  final num parameterLimit;
+
+  /// Change the duplicate ket handling strategy
   final Duplicates duplicates;
+
+  /// Set to [true] to ignore the leading question mark query prefix in the encoded input.
   final bool ignoreQueryPrefix;
+
+  /// Set to [true] to interpret HTML numeric entities (`&#...;`) in the encoded input.
   final bool interpretNumericEntities;
-  final num parameterLimit;
+
+  /// To disable [List] parsing entirely, set [parseLists] to [false].
   final bool parseLists;
+
+  /// Set to true to decode values without `=` to `null`.
   final bool strictNullHandling;
+
+  /// Set a [Decoder] to affect the decoding of the input.
   final Decoder? _decoder;
 
-  /// The decoder function to use.
+  /// Decode the input using the specified [Decoder].
   dynamic decoder(String? value, {Encoding? charset}) => _decoder is Function
       ? _decoder?.call(value, charset: charset)
       : Utils.decode(value, charset: charset);
 
+  /// Returns a new [DecodeOptions] instance with updated values.
   DecodeOptions copyWith({
     bool? allowDots,
     bool? allowEmptyLists,

test/unit/example.dart

@@ -50,8 +50,8 @@ void main() {
         }),
       );
 
-      /// By default, when nesting [Map]s qs will only parse up to 5 children deep.
-      /// This means if you attempt to parse a string like 'a[b][c][d][e][f][g][h][i]=j'
+      /// By default, when nesting [Map]s QS will only decode up to 5 children deep.
+      /// This means if you attempt to decode a string like 'a[b][c][d][e][f][g][h][i]=j'
       /// your resulting [Map] will be:
       expect(
         QS.decode('a[b][c][d][e][f][g][h][i]=j'),
@@ -71,7 +71,7 @@ void main() {
       );
 
       /// This depth can be overridden by setting the [DecodeOptions.depth].
-      /// The depth limit helps mitigate abuse when qs is used to parse user input,
+      /// The depth limit helps mitigate abuse when [QS] is used to parse user input,
       /// and it is recommended to keep it a reasonably small number:
       expect(
         QS.decode(