[observe] use consistent comment style

pkg/observe/lib/src/list_diff.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // 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.
 
 library observe.src.list_diff;
 
 import 'dart:math' as math;
 import 'dart:collection' show UnmodifiableListView;
 
-/**
- * A summary of an individual change to a [List].
- *
- * Each delta represents that at the [index], [removed] sequence of items were
- * removed, and counting forward from [index], [addedCount] items were added.
- */
+/// A summary of an individual change to a [List].
+///
+/// Each delta represents that at the [index], [removed] sequence of items were
+/// removed, and counting forward from [index], [addedCount] items were added.
 class ListChangeRecord {
-  /** The list that changed. */
+  /// The list that changed.
   final List object;
 
-  /** The index of the change. */
+  /// The index of the change.
   int get index => _index;
 
-  /** The items removed, if any. Otherwise this will be an empty list. */
+  /// The items removed, if any. Otherwise this will be an empty list.
   List get removed => _unmodifiableRemoved;
   UnmodifiableListView _unmodifiableRemoved;
 
-  /**
-   * Mutable version of [removed], used during the algorithms as they are
-   * constructing the object.
-   */
+  /// Mutable version of [removed], used during the algorithms as they are
+  /// constructing the object.
   List _removed;
 
-  /** The number of items added. */
+  /// The number of items added.
   int get addedCount => _addedCount;
 
   // Note: conceptually these are final, but for convenience we increment it as
   // we build the object. It will be "frozen" by the time it is returned the the
   // user.
   int _index, _addedCount;
 
   ListChangeRecord._(this.object, this._index, removed, this._addedCount)
       : _removed = removed,
         _unmodifiableRemoved = new UnmodifiableListView(removed);
 
   factory ListChangeRecord(List object, int index,
       {List removed, int addedCount}) {
 
     if (removed == null) removed = [];
     if (addedCount == null) addedCount = 0;
     return new ListChangeRecord._(object, index, removed, addedCount);
   }
 
-  /** Returns true if the provided index was changed by this operation. */
+  /// Returns true if the provided index was changed by this operation.
   bool indexChanged(key) {
     // If key isn't an int, or before the index, then it wasn't changed.
     if (key is! int || key < index) return false;
 
     // If this was a shift operation, anything after index is changed.
     if (addedCount != removed.length) return true;
 
     // Otherwise, anything in the update range was changed.
     return key < index + addedCount;
   }
@@ skipping 111 matching lines @@
 int _sharedSuffix(List arr1, List arr2, int searchLength) {
   var index1 = arr1.length;
   var index2 = arr2.length;
   var count = 0;
   while (count < searchLength && arr1[--index1] == arr2[--index2]) {
     count++;
   }
   return count;
 }
 
-/**
- * Lacking individual splice mutation information, the minimal set of
- * splices can be synthesized given the previous state and final state of an
- * array. The basic approach is to calculate the edit distance matrix and
- * choose the shortest path through it.
- *
- * Complexity: O(l * p)
- *   l: The length of the current array
- *   p: The length of the old array
- */
+/// Lacking individual splice mutation information, the minimal set of
+/// splices can be synthesized given the previous state and final state of an
+/// array. The basic approach is to calculate the edit distance matrix and
+/// choose the shortest path through it.
+///
+/// Complexity: O(l * p)
+///   l: The length of the current array
+///   p: The length of the old array
 List<ListChangeRecord> calcSplices(List current, int currentStart,
     int currentEnd, List old, int oldStart, int oldEnd) {
 
   var prefixCount = 0;
   var suffixCount = 0;
 
   var minLength = math.min(currentEnd - currentStart, oldEnd - oldStart);
   if (currentStart == 0 && oldStart == 0) {
     prefixCount = _sharedPrefix(current, old, minLength);
   }
@@ skipping 151 matching lines @@
 List<ListChangeRecord> _createInitialSplices(List<Object> list,
     List<ListChangeRecord> records) {
 
   var splices = <ListChangeRecord>[];
   for (var record in records) {
     _mergeSplice(splices, record);
   }
   return splices;
 }
 
-/**
- * We need to summarize change records. Consumers of these records want to
- * apply the batch sequentially, and ensure that they can find inserted
- * items by looking at that position in the list. This property does not
- * hold in our record-as-you-go records. Consider:
- *
- *     var model = toObservable(['a', 'b']);
- *     model.removeAt(1);
- *     model.insertAll(0, ['c', 'd', 'e']);
- *     model.removeRange(1, 3);
- *     model.insert(1, 'f');
- *
- * Here, we inserted some records and then removed some of them.
- * If someone processed these records naively, they would "play back" the
- * insert incorrectly, because those items will be shifted.
- */
+/// We need to summarize change records. Consumers of these records want to
+/// apply the batch sequentially, and ensure that they can find inserted
+/// items by looking at that position in the list. This property does not
+/// hold in our record-as-you-go records. Consider:
+///
+///     var model = toObservable(['a', 'b']);
+///     model.removeAt(1);
+///     model.insertAll(0, ['c', 'd', 'e']);
+///     model.removeRange(1, 3);
+///     model.insert(1, 'f');
+///
+/// Here, we inserted some records and then removed some of them.
+/// If someone processed these records naively, they would "play back" the
+/// insert incorrectly, because those items will be shifted.
 List<ListChangeRecord> projectListSplices(List list,
     List<ListChangeRecord> records) {
   if (records.length <= 1) return records;
 
   var splices = [];
   for (var splice in _createInitialSplices(list, records)) {
     if (splice.addedCount == 1 && splice.removed.length == 1) {
       if (splice.removed[0] != list[splice.index]) splices.add(splice);
       continue;
     }
 
     splices.addAll(calcSplices(list, splice.index,
         splice.index + splice.addedCount, splice._removed, 0,
         splice.removed.length));
   }
 
   return splices;
 }