comments only: update docs for SkStream::readData(), SkWStream::writeData()

include/core/SkStream.h

Index: include/core/SkStream.h
===================================================================
--- include/core/SkStream.h	(revision 8186)
+++ include/core/SkStream.h	(working copy)
@@ -66,8 +66,8 @@
     size_t   readPackedUInt();
 
     /**
-     *  Create a new SkData from the stream contents. This balances the call
-     *  SkWStream::writeData().
+     *  Reconstitute an SkData object that was written to the stream
+     *  using SkWStream::writeData().
      */
     SkData* readData();
 
@@ -108,6 +108,12 @@
 
     bool writeStream(SkStream* input, size_t length);
 
+    /**
+     * Append a representation of an SkData object to the stream.

[reed1, 2013/03/18 14:12:58]

Not sure what the reader is to infer from "representation", as I don't think we
use that term anywhere else in our dox. You comment sounds a little mysterious
:) What are you trying to communicate (or clarify)?

[epoger, 2013/03/18 22:25:51]

While an air of mystery can be fun, let's try to make it clear.

I'm just trying to warn would-be callers that this method DOES NOT just write
out the raw content of the SkData object.  (Or, more correctly, MIGHT NOT do so,
since you want to maintain flexibility to change the implementation over time.)

I'm open to any description that conveys that message.

Maybe this, or some variant?

* Append an SkData object to the stream, such that it can be read
* out of the stream using SkStream::readData().
*
* Note that the encoding method used to write the SkData object
* to the stream may change over time.  This method DOES NOT
* just write the raw content of the SkData object to the stream.

Anyway, if you have a better idea, just paste it here and I'll use it.

+     * Note that this representation may include data other than the
+     * raw content of the SkData object.
+     * The SkData object can be reconstituted using SkStream::readData().
+     */
     bool writeData(const SkData*);
 };