Fix various documentation issues.

sdk/lib/convert/json.dart

 // Copyright (c) 2013, 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 dart.convert;
 
 /**
  * Error thrown by JSON serialization if an object cannot be serialized.
  *
  * The [unsupportedObject] field holds that object that failed to be serialized.
@@ skipping 64 matching lines @@
    *
    * The [reviver] function is called during decoding. It is invoked
    * once for each object or list property that has been parsed.
    * The `key` argument is either the
    * integer list index for a list property, the string map key for object
    * properties, or `null` for the final result.
    *
    * If [reviver] is omitted, it defaults to returning the value argument.
    *
    * The [toEncodable] function is used during encoding. It is invoked for
-   * values that are not directly encodable to a JSON
+   * values that are not directly encodable to a JSON1toE

[Søren Gjesse, 2014/03/14 08:10:15]

What is "a JSON1toE string"?

    * string (a value that is not a number, boolean, string, null, list or a map
    * with string keys). The function must return an object that is directly
-   * encodable.
+   * encodable. The elements of a returned list and values of a returned map
+   * do not need be directly encodable, and if they aren't, `toEncodable` will
+   * be used on them as well.
+   * Please notice that it is possible to cause an infinite recursive
+   * regress in this way, by effectively creating an infinite data structure
+   * through repeated call to `toEncodable`.
    *
    * If [toEncodable] is omitted, it defaults to a function that returns the
    * result of calling `.toJson()` on the unencodable object.
    */
   const JsonCodec({reviver(var key, var value), toEncodable(var object)})
       : _reviver = reviver,
         _toEncodable = toEncodable;
 
   /**
    * Creates a `JsonCodec` with the given reviver.
@@ skipping 397 matching lines @@
         first = false;
       });
       _sink.write('}');
       _seen.remove(object);
       return true;
     } else {
       return false;
     }
   }
 }