Fix for mirror API breaking change to index libraries by URI, and clean up references in doc commen…

pkg/serialization/lib/src/basic_rule.dart

 // Copyright (c) 2012, 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.
 
 part of serialization;
 
 // TODO(alanknight): Figure out how to reasonably separate out the things
 // that require reflection without making the API more awkward. Or if that is
 // in fact necessary. Maybe the tree-shaking will just remove it if unused.
 
@@ skipping 206 matching lines @@
   /**
    * Call the designated constructor with the appropriate fields from [state],
    * first resolving references in the context of [reader].
    */
   inflateEssential(state, Reader reader) {
     InstanceMirror mirror = constructor.constructFrom(
         makeIndexableByNumber(state), reader);
     return mirror.reflectee;
   }
 
-  /** For all [state] not required in the constructor, set it in the [object],
-   * resolving references in the context of [reader].
+  /** For all [rawState] not required in the constructor, set it in the
+   * [object], resolving references in the context of [reader].
    */
   inflateNonEssential(rawState, object, Reader reader) {
     InstanceMirror mirror = reflect(object);
     var state = makeIndexableByNumber(rawState);
     fields.forEachRegularField( (_Field field) {
       var value = reader.inflateReference(state[field.index]);
       field.setValue(mirror, value);
     });
   }
 
@@ skipping 38 matching lines @@
 /**
  * This represents a field in an object. It is intended to be used as part of
  * a [_FieldList].
  */
 abstract class _Field implements Comparable<_Field> {
 
   /** The FieldList that contains us. */
   final _FieldList fieldList;
 
   /**
-   * Our position in the [contents] collection of [fieldList]. This is used
+   * Our position in the [fieldList._contents] collection. This is used
    * to index into the state, so it's extremely important.
    */
   int index;
 
   /** Is this field used in the constructor? */
   bool usedInConstructor = false;
 
   /**
    * Create a new [_Field] instance. This will be either a [_NamedField] or a
    * [_ConstantField] depending on whether or not [value] corresponds to a
@@ skipping 27 matching lines @@
   valueIn(InstanceMirror mirror);
 
   // TODO(alanknight): Is this the right name, or is it confusing that essential
   // is not the inverse of regular.
   /** Return true if this is field is not used in the constructor. */
   bool get isRegular => !usedInConstructor;
 
   /**
    * Return true if this field is treated as essential state, either because
    * it is used in the constructor, or because it's been designated
-   * using [setFieldWith].
+   * using [BasicRule.setFieldWith].
    */
   bool get isEssential => usedInConstructor;
 
   /** Set the [value] of our field in the given mirrored [object]. */
   void setValue(InstanceMirror object, value);
 
   // Because [x] may not be a named field, we compare the toString. We don't
   // care that much where constants come in the sort order as long as it's
   // consistent.
   compareTo(_Field x) => toString().compareTo(x.toString());
@@ skipping 24 matching lines @@
 
   String get name =>
       _name == null ? _name = MirrorSystem.getName(nameSymbol) : _name;
 
   operator ==(x) => x is _NamedField && (nameSymbol == x.nameSymbol);
   int get hashCode => name.hashCode;
 
   /**
    * Return true if this field is treated as essential state, either because
    * it is used in the constructor, or because it's been designated
-   * using [setFieldWith].
+   * using [BasicRule.setFieldWith].
    */
   bool get isEssential => super.isEssential || customSetter != null;
 
   /** Set the [value] of our field in the given mirrored [object]. */
   void setValue(InstanceMirror object, value) {
     setter(object, value);
   }
 
   valueIn(InstanceMirror mirror) => mirror.getField(nameSymbol).reflectee;
 
@@ skipping 212 matching lines @@
 class Constructor {
   /** The mirror of the class we construct. */
   final ClassMirror type;
 
   /** The name of the constructor to use, if not the default constructor.*/
   String name;
   Symbol nameSymbol;
 
   /**
    * The indices of the fields used as constructor arguments. We will look
-   * these up in the state by number. These correspond to the index in the
-   * [contents] of the FieldList, which will be alphabetically sorted.
+   * these up in the state by number. The index is according to a list of the
+   * fields in alphabetical order by name.
    */
   List<int> fieldNumbers;
 
   /**
    * Creates a new constructor for the [type] with the constructor named [name]
    * and the [fieldNumbers] of the constructor fields.
    */
   Constructor(this.type, this.name, this.fieldNumbers) {
     if (name == null) name = '';
     nameSymbol = new Symbol(name);
@@ skipping 48 matching lines @@
   if (value is String) {
     try {
       return new Symbol(value);
     } on ArgumentError {
       return null;
     };
   } else {
     return null;
   }
 }