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

include/core/SkStream.h

 
 /*
  * Copyright 2006 The Android Open Source Project
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 
 #ifndef SkStream_DEFINED
@@ skipping 48 matching lines @@
 
     uint8_t  readU8() { return (uint8_t)this->readS8(); }
     uint16_t readU16() { return (uint16_t)this->readS16(); }
     uint32_t readU32() { return (uint32_t)this->readS32(); }
 
     bool     readBool() { return this->readU8() != 0; }
     SkScalar readScalar();
     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();
 
 private:
     typedef SkRefCnt INHERITED;
 };
 
 class SK_API SkWStream : SkNoncopyable {
 public:
     SK_DECLARE_INST_COUNT_ROOT(SkWStream)
@@ skipping 20 matching lines @@
     bool    writeBigDecAsText(int64_t, int minDigits = 0);
     bool    writeHexAsText(uint32_t, int minDigits = 0);
     bool    writeScalarAsText(SkScalar);
 
     bool    writeBool(bool v) { return this->write8(v); }
     bool    writeScalar(SkScalar);
     bool    writePackedUInt(size_t);
 
     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*);
 };
 
 ////////////////////////////////////////////////////////////////////////////////////////
 
 #include "SkString.h"
 
 struct SkFILE;
 
 /** A stream that reads from a FILE*, which is opened in the constructor and
@@ skipping 252 matching lines @@
     virtual void newline() SK_OVERRIDE;
 
 private:
     typedef SkWStream INHERITED;
 };
 
 // for now
 typedef SkFILEStream SkURLStream;
 
 #endif