diff --git a/src/as/com/threerings/io/ObjectInputStream.as b/src/as/com/threerings/io/ObjectInputStream.as
index 1f83b056a..1a9c81b6f 100644
--- a/src/as/com/threerings/io/ObjectInputStream.as
+++ b/src/as/com/threerings/io/ObjectInputStream.as
@@ -154,11 +154,11 @@ public class ObjectInputStream
     }
 
     /**
+     * Called to read an Object of a known final type into a Streamable object.
+     *
      * @param type either a String representing the java type,
      *             or a Class object representing the actionscript type.
      */
-    // TODO: this is the equivalent of marshalling something for which
-    // we have a basic streamer. Fill out with all the java types
     public function readField (type :Object) :Object
         //throws IOError
     {
diff --git a/src/as/com/threerings/io/ObjectOutputStream.as b/src/as/com/threerings/io/ObjectOutputStream.as
index b0fe963bd..a8cbb9d60 100644
--- a/src/as/com/threerings/io/ObjectOutputStream.as
+++ b/src/as/com/threerings/io/ObjectOutputStream.as
@@ -106,7 +106,24 @@ public class ObjectOutputStream
     }
 
     /**
-     * This is equivalent to marshalling a field for which there is a basic streamer.
+     * Called to write an object reference within a Streamable object when the type of the
+     * field is a final type.
+     *
+     * @example This is how you would do it, even if s and o referred to the same String object!
+     * <listing version="3.0">
+     * public class Foo
+     *    implements Streamable
+     * {
+     *     public var o :Object;
+     *     public var s :String;
+     *   ...
+     *     public function writeObject (out :ObjectOutputStream) :void
+     *     {
+     *         out.writeObject(o);
+     *         out.writeField(s);
+     *     }
+     * }
+     * </listing>
      */
     public function writeField (val :Object) :void
         //throws IOError