Update the API documentations with Paul review comments.

pkg/analyzer/lib/src/dart/analysis/byte_store.dart

 // Copyright (c) 2015, 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.
 
 import 'dart:collection';
 
 /**
  * Store of bytes associated with string keys.
  *
+ * Each key must be not longer than 100 characters and consist of only `[a-z]`,
+ * `[0-9]`, `.` and `_` characters. It cannot have the sequence `..` in it.

[Paul Berry, 2016/10/23 21:10:18]

Two other constraints:
- the key can't be the literal string "."
- the key can't be the empty string

+ *
  * Note that associations are not guaranteed to be persistent. The value
- * associated with a key can change or become `null` at any point of time.
+ * associated with a key can change or become `null` at any point in time.
  */
 abstract class ByteStore {
   /**
    * Return the bytes associated with the given [key].
    * Return `null` if the association does not exist.
    */
   List<int> get(String key);
 
   /**
    * Associate the given [bytes] with the [key].
    */
   void put(String key, List<int> bytes);
 }
 
 /**
- * [ByteStore] with LRU cache.
+ * A wrapper around [ByteStore] which adds an in-memory LRU cache to it.
+ *
+ * TODO(scheglov) Consider implementing size and/or time eviction policies.
  */
 class MemoryCachingByteStore implements ByteStore {
   final ByteStore store;
   final int maxEntries;
 
   final _map = <String, List<int>>{};
   final _keys = new LinkedHashSet<String>();
 
   MemoryCachingByteStore(this.store, this.maxEntries);
 
@@ skipping 14 matching lines @@
   }
 
   void _evict() {
     if (_keys.length > maxEntries) {
       String key = _keys.first;
       _keys.remove(key);
       _map.remove(key);
     }
   }
 }