Tweaks to PPB_VarArrayBuffer in preperation for taking out of Dev.

ppapi/cpp/dev/var_array_buffer_dev.h

Index: ppapi/cpp/dev/var_array_buffer_dev.h
diff --git a/ppapi/cpp/dev/var_array_buffer_dev.h b/ppapi/cpp/dev/var_array_buffer_dev.h
index 6f8c9590294ed5edc88d57bdab7988cf1d40b171..e720d3fe858502143aee814786c0a00028d8513c 100644
--- a/ppapi/cpp/dev/var_array_buffer_dev.h
+++ b/ppapi/cpp/dev/var_array_buffer_dev.h
@@ -26,8 +26,11 @@ class VarArrayBuffer_Dev : public Var {
   /// @param[in] var An array buffer Var.
   explicit VarArrayBuffer_Dev(const Var& var);
 
+  /// Copy constructor.
   VarArrayBuffer_Dev(const VarArrayBuffer_Dev& buffer) : Var(buffer) {}

[bbudge, 2012/01/25 22:19:07]

pp::Var defines an assignment operator. Does it do the right thing?

[dmichael (off chromium), 2012/01/25 23:50:11]

Yes. I went ahead and added a simple VarArrayBuffer->VarArrayBuffer assignment
for consistency & convenience.

 
+  virtual ~VarArrayBuffer_Dev() {}
+
   /// Construct a new VarArrayBuffer_Dev which is size_in_bytes bytes long and
   /// initialized to zero.
   ///
@@ -39,13 +42,25 @@ class VarArrayBuffer_Dev : public Var {
   /// @return The length of the VarArrayBuffer_Dev in bytes.
   uint32_t ByteLength() const;
 
-  /// Return a pointer to the buffer associated with this VarArrayBuffer_Dev.
+  /// Maps the ArrayBuffer in to the module's address space and returns a
+  /// pointer to the beginning of the buffer for the given ArrayBuffer PP_Var.
+  /// Note that calling Map() can be a relatively expensive operation. Use care
+  /// when calling it in performance-critical code. For example, you should call
+  /// it only once when looping over an ArrayBuffer:
   ///
-  /// @return A pointer to the buffer associated with this VarArrayBuffer_Dev.
+  /// <code>
+  ///   char* data = static_cast<char*>(array_buffer_var.Map());
+  ///   uint32_t byte_length = array_buffer_var.ByteLength();
+  ///   for (uint32_t i = 0; i < byte_length; ++i)
+  ///     data[i] = 'A';
+  /// </code>
+  ///
+  /// @return A pointer to the buffer for this array.
   void* Map();
-  const void* Map() const;
 
-  virtual ~VarArrayBuffer_Dev() {}
+  /// Unmaps this ArrayBuffer var from the module address space. Use this if
+  /// you want to save memory but might want to Map the buffer again later.
+  void Unmap();

[bbudge, 2012/01/25 22:19:07]

same comment as for .idl, maybe standardize on VarArrayBuffer here.

[dmichael (off chromium), 2012/01/25 23:50:11]

Done.

 
  private:
   // We cache the buffer so that repeated calls to Map() are quick.