Fix documentation bugs 7517 and 7518 in serialization.

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.
  *
  * Setup
@@ skipping 27 matching lines @@
  * fields that we specified. We may also want to tell it to identify the
  * fields, but to specifically omit certain fields that we don't want
  * serialized.
  *
  *      var serialization = new Serialization()
  *        ..addRuleFor(address,
  *            constructor: "",
  *            excludeFields: ["other", "stuff"]);
  *
  * We can also use a completely non-reflective rule to serialize and
- * de-serialize objects.
+ * de-serialize objects. This can be more work for us, but can run via

[sethladd, 2012/12/22 00:06:24]

What do you mean "us" here?

perhaps, "This technique is more cumbersome, but it does work in dart2js (where
mirrors are not yet implement)."

[Alan Knight, 2012/12/22 00:31:21]

Done.

+ * dart2js where mirrors are not yet implemented, and even on the VM may
+ * have better performance.
  *
  *      addressToMap(a) => {"number" : a.number, "street" : a.street,
  *          "city" : a.city};
  *      createAddress(Map m) => new Address.create(m["number"], m["street"]);
  *      fillInAddress(Map m, Address a) => a.city = m["city"];
  *      var serialization = new Serialization()
  *        ..addRule(
  *            new ClosureToMapRule(anAddress.runtimeType,
  *                addressToMap, createAddress, fillInAddress);
  *
@@ skipping 165 matching lines @@
    * use for this is if we are reading self-describing serialized data and
    * will populate the rules from that data.
    */
   Serialization.blank() { }
 
   /**
    * Create a [BasicRule] rule for the type of
    * [instanceOfType]. Optionally
    * allows specifying a [constructor] name, the list of [constructorFields],
    * and the list of [fields] not used in the constructor. Returns the new
-   * rule.
+   * rule. Note that [BasicRule] uses reflection, and so will not work with the
+   * current state of dartj2s. If you need to run there, consider using
+   * [CustomRule] instead.
    *
    * If the optional parameters aren't specified, the default constructor will
    * be used, and the list of fields will be computed. Alternatively, you can
    * omit [fields] and provide [excludeFields], which will then compute the
    * list of fields specifically excluding those listed.
    *
    * The fields can be actual public fields, but can also be getter/setter
    * pairs or getters whose value is provided in the constructor. For the
    * [constructorFields] they can also be arbitrary objects. Anything that is
    * not a String will be treated as a constant value to be used in any
@@ skipping 182 matching lines @@
   }
 }
 
 /**
  * An exception class for errors during serialization.
  */
 class SerializationException implements Exception {
   final String message;
   const SerializationException([this.message]);
 }