Fix doc comment references among other new lints (#253)

Bump min SDK to 2.18

.github/workflows/ci.yml

@@ -46,7 +46,7 @@ jobs:
       matrix:
         # Add macos-latest and/or windows-latest if relevant for this package.
         os: [ubuntu-latest]
-        sdk: [2.12.0, dev]
+        sdk: [2.18.0, dev]
     steps:
       - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8
       - uses: dart-lang/setup-dart@6a218f2413a3e78e9087f638a238f6b40893203d

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.17.1-dev
+
+* Require Dart 2.18
+
 ## 1.17.0
 
 * Add `Iterable.elementAtOrNull` and `List.elementAtOrNull` extension methods.

analysis_options.yaml

@@ -1,14 +1,29 @@
 include: package:lints/recommended.yaml
 
+analyzer:
+  language:
+    strict-casts: true
+
 linter:
   rules:
+    - always_declare_return_types
     - avoid_dynamic_calls
-
-    # Errors
+    - avoid_unused_constructor_parameters
+    - cancel_subscriptions
+    - directives_ordering
+    - lines_longer_than_80_chars
+    - literal_only_boolean_expressions
+    - missing_whitespace_between_adjacent_strings
+    - no_adjacent_strings_in_list
+    - no_runtimeType_toString
+    - omit_local_variable_types
+    - package_api_docs
+    - prefer_relative_imports
+    - prefer_single_quotes
     - test_types_in_equals
     - throw_in_finally
-
-    # Style
-    - avoid_private_typedef_functions
-    - directives_ordering
-    - only_throw_errors
+    - type_annotate_public_apis
+    - unawaited_futures
+    - unnecessary_await_in_return
+    - unnecessary_lambdas
+    - use_super_parameters

lib/src/algorithms.dart

@@ -65,8 +65,8 @@ int binarySearchBy<E, K>(List<E> sortedList, K Function(E element) keyOf,
 /// If [compare] is omitted, this defaults to calling [Comparable.compareTo] on
 /// the objects. In this case, the objects must be [Comparable].
 ///
-/// Returns [sortedList.length] if all the items in [sortedList] compare less
-/// than [value].
+/// Returns the length of [sortedList] if all the items in [sortedList] compare
+/// less than [value].
 int lowerBound<E>(List<E> sortedList, E value, {int Function(E, E)? compare}) {
   compare ??= defaultCompare;
   return lowerBoundBy<E, E>(sortedList, identity, compare, value);
@@ -76,11 +76,13 @@ int lowerBound<E>(List<E> sortedList, E value, {int Function(E, E)? compare}) {
 ///
 /// Uses binary search to find the location of [value].
 /// This takes on the order of `log(n)` comparisons.
-/// Elements are compared using the [compare] function of the [keyOf] property of
-/// the elements.
-/// If the list isn't sorted according to this order, the result is unpredictable.
+/// Elements are compared using the [compare] function of the [keyOf] property
+/// of the elements.
+/// If the list isn't sorted according to this order, the result is
+/// unpredictable.
 ///
-/// Returns [sortedList.length] if all the items in [sortedList] are before [value].
+/// Returns the length of [sortedList] if all the items in [sortedList] are
+/// before [value].
 ///
 /// If [start] and [end] are supplied, only that range is searched,
 /// and only that range need to be sorted.
@@ -231,12 +233,12 @@ void mergeSort<E>(List<E> elements,
   var secondLength = end - middle;
   // secondLength is always the same as firstLength, or one greater.
   var scratchSpace = List<E>.filled(secondLength, elements[start]);
-  E Function(E) id = identity;
-  _mergeSort(elements, id, compare, middle, end, scratchSpace, 0);
+  _mergeSort(elements, identity<E>, compare, middle, end, scratchSpace, 0);
   var firstTarget = end - firstLength;
-  _mergeSort(elements, id, compare, start, middle, elements, firstTarget);
-  _merge(id, compare, elements, firstTarget, end, scratchSpace, 0, secondLength,
-      elements, start);
+  _mergeSort(
+      elements, identity<E>, compare, start, middle, elements, firstTarget);
+  _merge(identity<E>, compare, elements, firstTarget, end, scratchSpace, 0,
+      secondLength, elements, start);
 }
 
 /// Sort [elements] using a merge-sort algorithm.
@@ -408,7 +410,7 @@ void quickSort<E>(List<E> elements, int Function(E a, E b) compare,
   _quickSort<E, E>(elements, identity, compare, Random(), start, end);
 }
 
-/// Sort [elements] using a quick-sort algorithm.
+/// Sort [list] using a quick-sort algorithm.
 ///
 /// The elements are compared using [compare] on the value provided by [keyOf]
 /// on the element.

lib/src/boollist.dart

@@ -74,8 +74,9 @@ abstract class BoolList with ListMixin<bool> {
 
   /// Generates a [BoolList] of values.
   ///
-  /// Creates a [BoolList] with [length] positions and fills it with values created by
-  /// calling [generator] for each index in the range `0` .. `length - 1` in increasing order.
+  /// Creates a [BoolList] with [length] positions and fills it with values
+  /// created by calling [generator] for each index in the range
+  /// `0` .. `length - 1` in increasing order.
   ///
   /// The created list is fixed-length unless [growable] is true.
   factory BoolList.generate(

lib/src/canonicalized_map.dart

@@ -129,7 +129,7 @@ class CanonicalizedMap<C, K, V> implements Map<K, V> {
   void removeWhere(bool Function(K key, V value) test) =>
       _base.removeWhere((_, pair) => test(pair.key, pair.value));
 
-  @Deprecated("Use cast instead")
+  @Deprecated('Use cast instead')
   Map<K2, V2> retype<K2, V2>() => cast<K2, V2>();
 
   @override

lib/src/combined_wrappers/combined_iterable.dart

@@ -17,7 +17,7 @@ class CombinedIterableView<T> extends IterableBase<T> {
   /// The iterables that this combines.
   final Iterable<Iterable<T>> _iterables;
 
-  /// Creates a combined view of [iterables].
+  /// Creates a combined view of [_iterables].
   const CombinedIterableView(this._iterables);
 
   @override

lib/src/combined_wrappers/combined_list.dart

@@ -24,7 +24,7 @@ class CombinedListView<T> extends ListBase<T>
   /// The lists that this combines.
   final List<List<T>> _lists;
 
-  /// Creates a combined view of [lists].
+  /// Creates a combined view of [_lists].
   CombinedListView(this._lists);
 
   @override

lib/src/combined_wrappers/combined_map.dart

@@ -40,11 +40,11 @@ class CombinedMapView<K, V> extends UnmodifiableMapBase<K, V> {
     return null;
   }
 
-  /// The keys of [this].
+  /// The keys of `this`.
   ///
   /// The returned iterable has efficient `contains` operations, assuming the
-  /// iterables returned by the wrapped maps have efficient `contains` operations
-  /// for their `keys` iterables.
+  /// iterables returned by the wrapped maps have efficient `contains`
+  /// operations for their `keys` iterables.
   ///
   /// The `length` must do deduplication and thus is not optimized.
   ///

lib/src/empty_unmodifiable_set.dart

@@ -4,7 +4,8 @@
 
 import 'dart:collection';
 
-import 'package:collection/collection.dart';
+import 'unmodifiable_wrappers.dart';
+import 'wrappers.dart';
 
 /// An unmodifiable, empty set which can be constant.
 class EmptyUnmodifiableSet<E> extends IterableBase<E>
@@ -26,7 +27,7 @@ class EmptyUnmodifiableSet<E> extends IterableBase<E>
   Iterable<E> followedBy(Iterable<E> other) => DelegatingIterable(other);
   @override
   E? lookup(Object? element) => null;
-  @Deprecated("Use cast instead")
+  @Deprecated('Use cast instead')
   @override
   EmptyUnmodifiableSet<T> retype<T>() => EmptyUnmodifiableSet<T>();
   @override

lib/src/equality.dart

@@ -253,8 +253,7 @@ abstract class _UnorderedEquality<E, T extends Iterable<E>>
 /// of the other iterable, so that each pair are equal.
 class UnorderedIterableEquality<E> extends _UnorderedEquality<E, Iterable<E>> {
   const UnorderedIterableEquality(
-      [Equality<E> elementEquality = const DefaultEquality<Never>()])
-      : super(elementEquality);
+      [super.elementEquality = const DefaultEquality<Never>()]);
 
   @override
   bool isValidKey(Object? o) => o is Iterable<E>;
@@ -273,9 +272,7 @@ class UnorderedIterableEquality<E> extends _UnorderedEquality<E, Iterable<E>> {
 /// even if the [isValidKey] returns `false` for `null`.
 /// The [hash] of `null` is `null.hashCode`.
 class SetEquality<E> extends _UnorderedEquality<E, Set<E>> {
-  const SetEquality(
-      [Equality<E> elementEquality = const DefaultEquality<Never>()])
-      : super(elementEquality);
+  const SetEquality([super.elementEquality = const DefaultEquality<Never>()]);
 
   @override
   bool isValidKey(Object? o) => o is Set<E>;
@@ -437,7 +434,7 @@ class DeepCollectionEquality implements Equality {
         _unordered = true;
 
   @override
-  bool equals(e1, e2) {
+  bool equals(Object? e1, Object? e2) {
     if (e1 is Set) {
       return e2 is Set && SetEquality(this).equals(e1, e2);
     }

lib/src/iterable_extensions.dart

@@ -4,10 +4,9 @@
 
 import 'dart:math' show Random;
 
-import 'package:collection/src/utils.dart';
-
 import 'algorithms.dart';
 import 'functions.dart' as functions;
+import 'utils.dart';
 
 /// Extensions that apply to all iterables.
 ///
@@ -365,18 +364,19 @@ extension IterableExtension<T> on Iterable<T> {
   /// The [index] must not be negative.
   T? elementAtOrNull(int index) => skip(index).firstOrNull;
 
-  /// Associates the elements in [this] by the value returned by [key].
+  /// Associates the elements in `this` by the value returned by [key].
   ///
-  /// Returns a map from keys computed by [key] to the last value for which [key]
-  /// returns that key.
+  /// Returns a map from keys computed by [key] to the last value for which
+  /// [key] returns that key.
   Map<K, T> lastBy<K>(K Function(T) key) => functions.lastBy(this, key);
 
   /// Groups elements by [keyOf] then folds the elements in each group.
   ///
   /// A key is found for each element using [keyOf].
   /// Then the elements with the same key are all folded using [combine].
-  /// The first call to [combine] for a particular key receives [null] as
-  /// the previous value, the remaining ones receive the result of the previous call.
+  /// The first call to [combine] for a particular key receives `null` as
+  /// the previous value, the remaining ones receive the result of the previous
+  /// call.
   ///
   /// Can be used to _group_ elements into arbitrary collections.
   /// For example [groupSetsBy] could be written as:
@@ -431,7 +431,8 @@ extension IterableExtension<T> on Iterable<T> {
 
   /// Splits the elements into chunks before some elements.
   ///
-  /// Each element is checked using [test] for whether it should start a new chunk.
+  /// Each element is checked using [test] for whether it should start a new
+  /// chunk.
   /// If so, the elements since the previous chunk-starting element
   /// are emitted as a list.
   /// Any final elements are emitted at the end.
@@ -504,7 +505,8 @@ extension IterableExtension<T> on Iterable<T> {
   ///
   /// Example:
   /// ```dart
-  /// var parts = [1, 0, 2, 1, 5, 7, 6, 8, 9].splitAfterIndexed((i, v) => i < v);
+  /// var parts = [1, 0, 2, 1, 5, 7, 6, 8, 9]
+  ///   .splitAfterIndexed((i, v) => i < v);
   /// print(parts); // ([1, 0], [2, 1], [5, 7, 6], [8, 9])
   /// ```
   Iterable<List<T>> splitAfterIndexed(
@@ -568,10 +570,10 @@ extension IterableExtension<T> on Iterable<T> {
     return true;
   }
 
-  /// Contiguous [slice]s of [this] with the given [length].
+  /// Contiguous slices of `this` with the given [length].
   ///
   /// Each slice is [length] elements long, except for the last one which may be
-  /// shorter if [this] contains too few elements. Each slice begins after the
+  /// shorter if `this` contains too few elements. Each slice begins after the
   /// last one ends. The [length] must be greater than zero.
   ///
   /// For example, `{1, 2, 3, 4, 5}.slices(2)` returns `([1, 2], [3, 4], [5])`.

lib/src/list_extensions.dart

@@ -28,13 +28,13 @@ extension ListExtensions<E> on List<E> {
   ///
   /// Uses binary search to find the location of [element].
   /// This takes on the order of `log(n)` comparisons.
-  /// The list *must* be sorted according to [compare] on the [keyOf] of elements,
-  /// otherwise the result is unspecified.
+  /// The list *must* be sorted according to [compare] on the [keyOf] of
+  /// elements, otherwise the result is unspecified.
   ///
   /// Returns -1 if [element] does not occur in this list.
   ///
-  /// If [start] and [end] are supplied, only the list range from [start] to [end]
-  /// is searched, and only that range needs to be sorted.
+  /// If [start] and [end] are supplied, only the list range from [start] to
+  /// [end] is searched, and only that range needs to be sorted.
   int binarySearchByCompare<K>(
           E element, K Function(E element) keyOf, int Function(K, K) compare,
           [int start = 0, int? end]) =>
@@ -50,8 +50,8 @@ extension ListExtensions<E> on List<E> {
   ///
   /// Returns -1 if [element] does not occur in this list.
   ///
-  /// If [start] and [end] are supplied, only the list range from [start] to [end]
-  /// is searched, and only that range needs to be sorted.
+  /// If [start] and [end] are supplied, only the list range from [start] to
+  /// [end] is searched, and only that range needs to be sorted.
   int binarySearchBy<K extends Comparable<K>>(
           E element, K Function(E element) keyOf, [int start = 0, int? end]) =>
       algorithms.binarySearchBy<E, K>(
@@ -270,10 +270,10 @@ extension ListExtensions<E> on List<E> {
   /// The [index] must not be negative.
   E? elementAtOrNull(int index) => (index < length) ? this[index] : null;
 
-  /// Contiguous [slice]s of [this] with the given [length].
+  /// Contiguous [slice]s of `this` with the given [length].
   ///
   /// Each slice is a view of this list [length] elements long, except for the
-  /// last one which may be shorter if [this] contains too few elements. Each
+  /// last one which may be shorter if `this` contains too few elements. Each
   /// slice begins after the last one ends.
   ///
   /// As with [slice], these slices are backed by this list, which must not

lib/src/priority_queue.dart

@@ -52,7 +52,7 @@ abstract class PriorityQueue<E> {
   /// Uses the [Object.==] of elements in the queue to check
   /// for whether they are equal to [object].
   /// Equal objects objects must have the same priority
-  /// according to the [comparison] function.
+  /// according to the comparison function.
   /// That is, if `a == b` then `comparison(a, b) == 0`.
   /// If that is not the case, this check might fail to find
   /// an object.
@@ -88,7 +88,7 @@ abstract class PriorityQueue<E> {
   ///
   /// Repeatedly calling this method, without adding element in between,
   /// is guaranteed to return elements in non-decreasing order as, specified by
-  /// [comparison].
+  /// the `comparison` constructor parameter.
   ///
   /// The queue must not be empty when this method is called.
   E removeFirst();
@@ -104,7 +104,7 @@ abstract class PriorityQueue<E> {
   /// Uses the [Object.==] of elements in the queue to check
   /// for whether they are equal to [element].
   /// Equal objects objects must have the same priority
-  /// according to the [comparison] function.
+  /// according to the `comparison` function.
   /// That is, if `a == b` then `comparison(a, b) == 0`.
   /// If that is not the case, this check might fail to find
   /// an object.

lib/src/queue_list.dart

@@ -115,7 +115,7 @@ class QueueList<E> extends Object with ListMixin<E> implements Queue<E> {
 
   QueueList<T> cast<T>() => QueueList._castFrom<E, T>(this);
 
-  @Deprecated("Use cast instead")
+  @Deprecated('Use cast instead')
   QueueList<T> retype<T>() => cast<T>();
 
   @override

lib/src/union_set.dart

@@ -36,7 +36,7 @@ class UnionSet<E> extends SetBase<E> with UnmodifiableSetMixin<E> {
   /// Creates a new set that's a view of the union of all sets in [sets].
   ///
   /// If any sets in [sets] change, this [UnionSet] reflects that change.
-  /// However, unlike [new UnionSet], this creates a copy of its parameter, so
+  /// However, unlike [UnionSet.new], this creates a copy of its parameter, so
   /// changes in [sets] aren't reflected in this [UnionSet].
   ///
   /// If [disjoint] is `true`, then all component sets must be disjoint. That

lib/src/union_set_controller.dart

@@ -22,7 +22,7 @@ import 'union_set.dart';
 /// }
 /// ```
 class UnionSetController<E> {
-  /// The [UnionSet] that provides a view of the union of sets in [this].
+  /// The [UnionSet] that provides a view of the union of sets in `this`.
   final UnionSet<E> set;
 
   /// The sets whose union is exposed through [set].
@@ -32,7 +32,7 @@ class UnionSetController<E> {
   ///
   /// If [disjoint] is `true`, this assumes that all component sets are
   /// disjoint—that is, that they contain no elements in common. This makes
-  /// many operations including [length] more efficient.
+  /// many operations including `length` more efficient.
   UnionSetController({bool disjoint = false}) : this._(<Set<E>>{}, disjoint);
 
   /// Creates a controller with the provided [_sets].
@@ -49,7 +49,7 @@ class UnionSetController<E> {
 
   /// Removes the contents of [component] to [set].
   ///
-  /// If another set in [this] has overlapping elements with [component], those
+  /// If another set in `this` has overlapping elements with [component], those
   /// elements will remain in [set].
   bool remove(Set<E> component) => _sets.remove(component);
 }