Modernize the package's style.

lib/src/algorithms.dart

Index: lib/src/algorithms.dart
diff --git a/lib/algorithms.dart b/lib/src/algorithms.dart
similarity index 69%
copy from lib/algorithms.dart
copy to lib/src/algorithms.dart
index 80f01070760209593dc3412618a1e3c3dd5abcb6..2b66d7df7014cfe921afa2592d5b447e0dc6ed2a 100644
--- a/lib/algorithms.dart
+++ b/lib/src/algorithms.dart
@@ -2,14 +2,9 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-/**
- * Operations on collections.
- */
-library dart.pkg.collection.algorithms;
+import "dart:math" as math;
 
-import "dart:math" show Random;
-
-/** Version of [binarySearch] optimized for comparable keys */
+/// Version of [binarySearch] optimized for comparable keys
 int _comparableBinarySearch(List<Comparable> list, Comparable value) {
   int min = 0;
   int max = list.length;
@@ -27,17 +22,15 @@ int _comparableBinarySearch(List<Comparable> list, Comparable value) {
   return -1;
 }
 
-/**
- * Returns a position of the [value] in [sortedList], if it is there.
- *
- * If the list isn't sorted according to the [compare] function, the result
- * is unpredictable.
- *
- * If [compare] is omitted, it defaults to calling [Comparable.compareTo] on
- * the objects.
- *
- * Returns -1 if [value] is not in the list by default.
- */
+/// Returns a position of the [value] in [sortedList], if it is there.
+///
+/// If the list isn't sorted according to the [compare] function, the result
+/// is unpredictable.
+///
+/// If [compare] is omitted, it defaults to calling [Comparable.compareTo] on
+/// the objects.
+///
+/// Returns -1 if [value] is not in the list by default.
 int binarySearch(List sortedList, value, { int compare(a, b) }) {
   if (compare == null) {
     return _comparableBinarySearch(sortedList, value);
@@ -58,7 +51,7 @@ int binarySearch(List sortedList, value, { int compare(a, b) }) {
   return -1;
 }
 
-/** Version of [lowerBound] optimized for comparable keys */
+/// Version of [lowerBound] optimized for comparable keys
 int _comparableLowerBound(List<Comparable> list, Comparable value) {
   int min = 0;
   int max = list.length;
@@ -75,19 +68,17 @@ int _comparableLowerBound(List<Comparable> list, Comparable value) {
   return min;
 }
 
-/**
- * Returns the first position in [sortedList] that does not compare less than
- * [value].
- *
- * If the list isn't sorted according to the [compare] function, the result
- * is unpredictable.
- *
- * If [compare] is omitted, it defaults to calling [Comparable.compareTo] on
- * the objects.
- *
- * Returns [sortedList.length] if all the items in [sortedList] compare less
- * than [value].
- */
+/// Returns the first position in [sortedList] that does not compare less than
+/// [value].
+///
+/// If the list isn't sorted according to the [compare] function, the result
+/// is unpredictable.
+///
+/// If [compare] is omitted, it defaults to calling [Comparable.compareTo] on
+/// the objects.
+///
+/// Returns [sortedList.length] if all the items in [sortedList] compare less
+/// than [value].
 int lowerBound(List sortedList, value, { int compare(a, b) }) {
   if (compare == null) {
     return _comparableLowerBound(sortedList, value);
@@ -107,13 +98,11 @@ int lowerBound(List sortedList, value, { int compare(a, b) }) {
   return min;
 }
 
-/**
- * Shuffles a list randomly.
- *
- * A sub-range of a list can be shuffled by providing [start] and [end].
- */
+/// Shuffles a list randomly.
+///
+/// A sub-range of a list can be shuffled by providing [start] and [end].
 void shuffle(List list, [int start = 0, int end = null]) {
-  Random random = new Random();
+  var random = new math.Random();
   if (end == null) end = list.length;
   int length = end - start;
   while (length > 1) {
@@ -126,15 +115,13 @@ void shuffle(List list, [int start = 0, int end = null]) {
 }
 
 
-/**
- * Reverses a list, or a part of a list, in-place.
- */
+/// Reverses a list, or a part of a list, in-place.
 void reverse(List list, [int start = 0, int end = null]) {
   if (end == null) end = list.length;
   _reverse(list, start, end);
 }
 
-// Internal helper function that assumes valid arguments.
+/// Internal helper function that assumes valid arguments.
 void _reverse(List list, int start, int end) {
   for (int i = start, j = end - 1; i < j; i++, j--) {
     var tmp = list[i];
@@ -143,19 +130,17 @@ void _reverse(List list, int start, int end) {
   }
 }
 
-/**
- * Sort a list using insertion sort.
- *
- * Insertion sort is a simple sorting algorithm. For `n` elements it does on
- * the order of `n * log(n)` comparisons but up to `n` squared moves. The
- * sorting is performed in-place, without using extra memory.
- *
- * For short lists the many moves have less impact than the simple algorithm,
- * and it is often the favored sorting algorithm for short lists.
- *
- * This insertion sort is stable: Equal elements end up in the same order
- * as they started in.
- */
+/// Sort a list using insertion sort.
+///
+/// Insertion sort is a simple sorting algorithm. For `n` elements it does on
+/// the order of `n * log(n)` comparisons but up to `n` squared moves. The
+/// sorting is performed in-place, without using extra memory.
+///
+/// For short lists the many moves have less impact than the simple algorithm,
+/// and it is often the favored sorting algorithm for short lists.
+///
+/// This insertion sort is stable: Equal elements end up in the same order
+/// as they started in.
 void insertionSort(List list,
                    { int compare(a, b),
                      int start: 0,
@@ -167,13 +152,11 @@ void insertionSort(List list,
   _insertionSort(list, compare, start, end, start + 1);
 }
 
-/**
- * Internal helper function that assumes arguments correct.
- *
- * Assumes that the elements up to [sortedUntil] (not inclusive) are
- * already sorted. The [sortedUntil] values should always be at least
- * `start + 1`.
- */
+/// Internal helper function that assumes arguments correct.
+///
+/// Assumes that the elements up to [sortedUntil] (not inclusive) are
+/// already sorted. The [sortedUntil] values should always be at least
+/// `start + 1`.
 void _insertionSort(List list, int compare(a, b), int start, int end,
                     int sortedUntil) {
   for (int pos = sortedUntil; pos < end; pos++) {
@@ -194,22 +177,20 @@ void _insertionSort(List list, int compare(a, b), int start, int end,
   }
 }
 
-/** Limit below which merge sort defaults to insertion sort. */
+/// Limit below which merge sort defaults to insertion sort.
 const int _MERGE_SORT_LIMIT = 32;
 
-/**
- * Sorts a list, or a range of a list, using the merge sort algorithm.
- *
- * Merge-sorting works by splitting the job into two parts, sorting each
- * recursively, and then merging the two sorted parts.
- *
- * This takes on the order of `n * log(n)` comparisons and moves to sort
- * `n` elements, but requires extra space of about the same size as the list
- * being sorted.
- *
- * This merge sort is stable: Equal elements end up in the same order
- * as they started in.
- */
+/// Sorts a list, or a range of a list, using the merge sort algorithm.
+///
+/// Merge-sorting works by splitting the job into two parts, sorting each
+/// recursively, and then merging the two sorted parts.
+///
+/// This takes on the order of `n * log(n)` comparisons and moves to sort
+/// `n` elements, but requires extra space of about the same size as the list
+/// being sorted.
+///
+/// This merge sort is stable: Equal elements end up in the same order
+/// as they started in.
 void mergeSort(List list, {int start: 0, int end: null, int compare(a, b)}) {
   if (end == null) end = list.length;
   if (compare == null) compare = Comparable.compare;
@@ -239,12 +220,10 @@ void mergeSort(List list, {int start: 0, int end: null, int compare(a, b)}) {
          list, start);
 }
 
-/**
- * Performs an insertion sort into a potentially different list than the
- * one containing the original values.
- *
- * It will work in-place as well.
- */
+/// Performs an insertion sort into a potentially different list than the
+/// one containing the original values.
+///
+/// It will work in-place as well.
 void _movingInsertionSort(List list, int compare(a, b), int start, int end,
                           List target, int targetOffset) {
   int length = end - start;
@@ -268,15 +247,13 @@ void _movingInsertionSort(List list, int compare(a, b), int start, int end,
   }
 }
 
-/**
- * Sorts [list] from [start] to [end] into [target] at [targetOffset].
- *
- * The `target` list must be able to contain the range from `start` to `end`
- * after `targetOffset`.
- *
- * Allows target to be the same list as [list], as long as it's not
- * overlapping the `start..end` range.
- */
+/// Sorts [list] from [start] to [end] into [target] at [targetOffset].
+///
+/// The `target` list must be able to contain the range from `start` to `end`
+/// after `targetOffset`.
+///
+/// Allows target to be the same list as [list], as long as it's not
+/// overlapping the `start..end` range.
 void _mergeSort(List list, int compare(a, b), int start, int end,
                 List target, int targetOffset) {
   int length = end - start;
@@ -302,16 +279,14 @@ void _mergeSort(List list, int compare(a, b), int start, int end,
          target, targetOffset);
 }
 
-/**
- * Merges two lists into a target list.
- *
- * One of the input lists may be positioned at the end of the target
- * list.
- *
- * For equal object, elements from [firstList] are always preferred.
- * This allows the merge to be stable if the first list contains elements
- * that started out earlier than the ones in [secondList]
- */
+/// Merges two lists into a target list.
+///
+/// One of the input lists may be positioned at the end of the target
+/// list.
+///
+/// For equal object, elements from [firstList] are always preferred.
+/// This allows the merge to be stable if the first list contains elements
+/// that started out earlier than the ones in [secondList]
 void _merge(int compare(a, b),
             List firstList, int firstStart, int firstEnd,
             List secondList, int secondStart, int secondEnd,