[api] Clarify expectations of ArrayBuffer::Allocator in API

BUG=chromium:611688
LOG=Y
R=jochen@chromium.org

Review-Url: https://codereview.chromium.org/1978773002
Cr-Commit-Position: refs/heads/master@{#36231}

include/v8.h

@@ -3453,10 +3453,20 @@ enum class ArrayBufferCreationMode { kInternalized, kExternalized };
 class V8_EXPORT ArrayBuffer : public Object {
  public:
   /**
-   * Allocator that V8 uses to allocate |ArrayBuffer|'s memory.
+   * A thread-safe allocator that V8 uses to allocate |ArrayBuffer|'s memory.
    * The allocator is a global V8 setting. It has to be set via
    * Isolate::CreateParams.
    *
+   * Memory allocated through this allocator by V8 is accounted for as external
+   * memory by V8. Note that V8 keeps track of the memory for all internalized
+   * |ArrayBuffer|s. Responsibility for tracking external memory (using
+   * Isolate::AdjustAmountOfExternalAllocatedMemory) is handed over to the
+   * embedder upon externalization and taken over upon internalization (creating
+   * an internalized buffer from an existing buffer).
+   *
+   * Note that it is unsafe to call back into V8 from any of the allocator
+   * functions.
+   *
    * This API is experimental and may change significantly.
    */
   class V8_EXPORT Allocator { // NOLINT