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

comments only: update docs for SkStream::readData(), SkWStream::writeData()
BUG=https://code.google.com/p/skia/issues/detail?id=1167
Committed: https://code.google.com/p/skia/source/detail?r=8260

[epoger, 2013-03-18 11:41:01]

note to self: in sk yellow on laptop

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

https://codereview.chromium.org/12604012/diff/1/include/core/SkStream.h
File include/core/SkStream.h (right):

https://codereview.chromium.org/12604012/diff/1/include/core/SkStream.h#newco...
include/core/SkStream.h:112: * Append a representation of an SkData object to
the stream.
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]

https://codereview.chromium.org/12604012/diff/1/include/core/SkStream.h
File include/core/SkStream.h (right):

https://codereview.chromium.org/12604012/diff/1/include/core/SkStream.h#newco...
include/core/SkStream.h:112: * Append a representation of an SkData object to
the stream.
On 2013/03/18 14:12:58, reed1 wrote:
> 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)?

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.

[reed1, 2013-03-19 12:21:33]

On 2013/03/18 22:25:51, epoger wrote:
> https://codereview.chromium.org/12604012/diff/1/include/core/SkStream.h
> File include/core/SkStream.h (right):
> 
>
https://codereview.chromium.org/12604012/diff/1/include/core/SkStream.h#newco...
> include/core/SkStream.h:112: * Append a representation of an SkData object to
> the stream.
> On 2013/03/18 14:12:58, reed1 wrote:
> > 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)?
> 
> 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.

I like your new description.

[epoger, 2013-03-20 15:56:08]

Committed patchset #3 manually as r8260 (presubmit successful).