serialization library-level doc comments

pkg/serialization/lib/serialization.dart

Index: pkg/serialization/lib/serialization.dart
diff --git a/pkg/serialization/lib/serialization.dart b/pkg/serialization/lib/serialization.dart
index 9323ec114f288728052b1f98a908252d95c6362c..6535da16be47a66b444ab771406e5f80ec620c88 100644
--- a/pkg/serialization/lib/serialization.dart
+++ b/pkg/serialization/lib/serialization.dart
@@ -3,25 +3,17 @@
 // 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 ##
- *
- * Use [pub][] to install this package. Add the following to your `pubspec.yaml`
- * file.
+ * A general-purpose serialization facility for Dart objects.
  *
- *     dependencies:
- *       serialization: any
+ * A [Serialization] is defined in terms of [SerializationRule]s and supports
+ * reading and writing to different formats.
  *
- * Then run `pub install`.
+ * For information on installing and importing this library, see the
+ * [serialization package on pub.dartlang.org]
+ * (http://pub.dartlang.org/packages/serialization).
  *
- * For more information, see the
- * [serialization package on pub.dartlang.org][pkg].
+ * ## Setup
  *
- * Setup
- * =====
  * A simple example of usage is
  *
  *      var address = new Address();
@@ -59,8 +51,8 @@
  *            constructor: "",
  *            excludeFields: ["other", "stuff"]);
  *
- * Writing Rules
- * =============
+ * ## Writing rules
+ *
  * We can also use a completely non-reflective rule to serialize and
  * de-serialize objects. This can be more work, but it does work in
  * dart2js, where mirrors are not yet implemented. We can specify this in two
@@ -117,8 +109,8 @@
  * consistent with the representation it uses. We pass it the runtimeType
  * of the object, and functions equivalent to the methods on [CustomRule]
  *
- * Constant Values
- * ===============
+ * ## Constant values
+ * 
  * There are cases where the constructor needs values that we can't easily get
  * from the serialized object. For example, we may just want to pass null, or a
  * constant value. To support this, we can specify as constructor fields
@@ -135,8 +127,8 @@
  *       s..addRuleFor(fooHolderInstance).setFieldWith("foo",
  *           (parent, value) => for (var each in value) parent.addFoo(value));
  *
- * Writing
- * =======
+ * ## Writing
+ *
  * To write objects, we use the write() method.
  *
  *       var output = serialization.write(someObject);
@@ -163,8 +155,8 @@
  *
  * These representations are not yet considered stable.
  *
- * Reading
- * =======
+ * ## Reading
+ *
  * To read objects, the corresponding [Serialization.read] method can be used.
  *
  *       Address input = serialization.read(input);
@@ -184,8 +176,8 @@
  * other services might expect. Using CustomRule or ClosureRule also does not
  * yet work with the [Serialization.selfDescribing] variable.
  *
- * Named Objects
- * =============
+ * ## 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
@@ -199,9 +191,6 @@
  *     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
  */
 library serialization;