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

pkg/serialization/lib/serialization.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.
 
 /**
  * This provides a general-purpose serialization facility for Dart objects. A
  * [Serialization] is defined in terms of [SerializationRule]s and supports
  * reading and writing to different formats.
  *
  * ## Installing ##
@@ skipping 59 matching lines @@
  *      class AddressRule extends CustomRule {
  *        bool appliesTo(instance, Writer w) => instance.runtimeType == Address;
  *        getState(instance) => [instance.street, instance.city];
  *        create(state) => new Address();
  *        setState(Address a, List state) {
  *          a.street = state[0];
  *          a.city = state[1];
  *        }
  *      }
  *
- * The class needs four different methods. The [appliesTo] method tells us if
+ * The class needs four different methods. The [CustomRule.appliesTo]
+ * method tells us if
  * the rule should be used to write an object. In this example we use a test
  * based on runtimeType. We could also use an "is Address" test, but if Address
  * has subclasses that would find those as well, and we want a separate rule
- * for each. The [getState] method should
+ * for each. The [CustomRule.getState] method should
  * return all the state of the object that we want to recreate,
  * and should be either a Map or a List. If you want to write to human-readable
  * formats where it's useful to be able to look at the data as a map from
  * field names to values, then it's better to return it as a map. Otherwise it's
  * more efficient to return it as a list. You just need to be sure that the
- * [create] and [setState] methods interpret the same way as [getState] does.
+ * [CustomRule.create] and [CustomRule.setState] methods interpret the data the
+ * same way as [CustomRule.getState] does.
  *
- * The [create] method will create the new object and return it. While it's
+ * The [CustomRule.create] method will create the new object and return it. While it's
  * possible to create the object and set all its state in this one method, that
  * increases the likelihood of problems with cycles. So it's better to use the
- * minimum necessary information in [create] and do more of the work in
- * [setState].
+ * minimum necessary information in [CustomRule.create] and do more of the work
+ * in [CustomRule.setState].
  *
  * The other way to do this is not creating a subclass, but by using a
  * [ClosureRule] and giving it functions for how to create
  * the address.
  *
  *      addressToMap(a) => {"number" : a.number, "street" : a.street,
  *          "city" : a.city};
  *      createAddress(Map m) => new Address.create(m["number"], m["street"]);
  *      fillInAddress(Address a, Map m) => a.city = m["city"];
  *      var serialization = new Serialization()
@@ skipping 32 matching lines @@
  *
  *       var output = serialization.write(someObject);
  *
  * By default this uses a representation in which objects are represented as
  * maps keyed by field name, but in which references between objects have been
  * converted into Reference objects. This is then typically encoded as
  * a [json] string, but can also be used in other ways, e.g. sent to another
  * isolate.
  *
  * We can write objects in different formats by passing a [Format] object to
- * the [write] method or by getting a [Writer] object. The available formats
+ * the [Serialization.write] method or by getting a [Writer] object.
+ * The available formats
  * include the default, a simple "flat" format that doesn't include field names,
  * and a simple JSON format that produces output more suitable for talking to
  * services that expect JSON in a predefined format. Examples of these are
  *
  *      Map output = serialization.write(address, new SimpleMapFormat());
  *      List output = serialization.write(address, new SimpleFlatFormat());
  *      var output = serialization.write(address, new SimpleJsonFormat());
  * Or, using a [Writer] explicitly
  *      var writer = serialization.newWriter(new SimpleFlatFormat());
  *      List output = writer.write(address);
  *
  * These representations are not yet considered stable.
  *
  * Reading
  * =======
- * To read objects, the corresponding [read] method can be used.
+ * To read objects, the corresponding [Serialization.read] method can be used.
  *
  *       Address input = serialization.read(input);
  *
  * When reading, the serialization instance doing the reading must be configured
  * with compatible rules to the one doing the writing. It's possible for the
  * rules to be different, but they need to be able to read the same
  * representation. For most practical purposes right now they should be the
  * same. The simplest way to achieve this is by having the serialization
- * variable [selfDescribing] be true. In that case the rules themselves are also
+ * variable [Serialization.selfDescribing] be true. In that case the rules
+ * themselves are also
  * stored along with the serialized data, and can be read back on the receiving
  * end. Note that this may not work for all rules or all formats. The
- * [selfDescribing] variable is true by default, but the [SimpleJsonFormat] does
- * not support it, since the point is to provide a representation in a form
+ * [Serialization.selfDescribing] variable is true by default, but the
+ * [SimpleJsonFormat] does not support it, since the point is to provide a
+ * representation in a form
  * other services might expect. Using CustomRule or ClosureRule also does not
- * yet work with the [selfDescribing] variable.
+ * yet work with the [Serialization.selfDescribing] variable.
  *
  * Named Objects
  * =============
  * When reading, some object references should not be serialized, but should be
  * connected up to other instances on the receiving side. A notable example of
  * this is when serialization rules have been stored. Instances of BasicRule
  * take a [ClassMirror] in their constructor, and we cannot serialize those. So
  * when we read the rules, we must provide a Map<String, Object> which maps from
  * the simple name of classes we are interested in to a [ClassMirror]. This can
- * be provided either in the [namedObjects] variable of the Serialization,
+ * be provided either in the [Serialization.namedObjects],
  * or as an additional parameter to the reading and writing methods on the
  * [Reader] or [Writer] respectively.
  *
  *     new Serialization()
  *       ..addRuleFor(new Person(), constructorFields: ["name"])
  *       ..namedObjects['Person'] = reflect(new Person()).type;
  *
  * [pub]: http://pub.dartlang.org
  * [pkg]: http://pub.dartlang.org/packages/serialization
  */
@@ skipping 286 matching lines @@
 }
 
 /**
  * An exception class for errors during serialization.
  */
 class SerializationException implements Exception {
   final String message;
   const SerializationException([this.message]);
   toString() => "SerializationException($message)";
 }