Clipboard: Add more detailed comments to ClipboardReader.

Bug: 1145787
Change-Id: Ia71ecf07d24f8d0f684c18a548da28e5b0b4c8ec
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2520325
Commit-Queue: Darwin Huang <huangdarwin@chromium.org>
Commit-Queue: Victor Costan <pwnall@chromium.org>
Reviewed-by: Victor Costan <pwnall@chromium.org>
Auto-Submit: Darwin Huang <huangdarwin@chromium.org>
Cr-Commit-Position: refs/heads/master@{#824704}

third_party/blink/renderer/modules/clipboard/clipboard_reader.cc

@@ -24,7 +24,7 @@ namespace blink {
 
 namespace {  // anonymous namespace for ClipboardReader's derived classes.
 
-// Reads an image from the System Clipboard as a blob with image/png content.
+// Reads an image from the System Clipboard as a Blob with image/png content.
 class ClipboardImageReader final : public ClipboardReader {
  public:
   explicit ClipboardImageReader(SystemClipboard* system_clipboard,
@@ -89,7 +89,7 @@ class ClipboardImageReader final : public ClipboardReader {
   }
 };
 
-// Reads an image from the System Clipboard as a blob with text/plain content.
+// Reads an image from the System Clipboard as a Blob with text/plain content.
 class ClipboardTextReader final : public ClipboardReader {
  public:
   explicit ClipboardTextReader(SystemClipboard* system_clipboard,
@@ -123,7 +123,7 @@ class ClipboardTextReader final : public ClipboardReader {
       scoped_refptr<base::SingleThreadTaskRunner> clipboard_task_runner) {
     DCHECK(!IsMainThread());
 
-    // Encode WTF String to UTF-8, the standard text format for blobs.
+    // Encode WTF String to UTF-8, the standard text format for Blobs.
     StringUTF8Adaptor utf8_text(plain_text);
     Vector<uint8_t> utf8_bytes;
     utf8_bytes.ReserveInitialCapacity(utf8_text.size());
@@ -146,7 +146,7 @@ class ClipboardTextReader final : public ClipboardReader {
   }
 };
 
-// Reads HTML from the System Clipboard as a blob with text/html content.
+// Reads HTML from the System Clipboard as a Blob with text/html content.
 class ClipboardHtmlReader final : public ClipboardReader {
  public:
   explicit ClipboardHtmlReader(SystemClipboard* system_clipboard,
@@ -219,7 +219,7 @@ class ClipboardHtmlReader final : public ClipboardReader {
   }
 };
 
-// Reads SVG from the System Clipboard as a blob with image/svg content.
+// Reads SVG from the System Clipboard as a Blob with image/svg content.
 class ClipboardSvgReader final : public ClipboardReader {
  public:
   ClipboardSvgReader(SystemClipboard* system_clipboard,
@@ -272,7 +272,7 @@ class ClipboardSvgReader final : public ClipboardReader {
       scoped_refptr<base::SingleThreadTaskRunner> clipboard_task_runner) {
     DCHECK(!IsMainThread());
 
-    // Encode WTF String to UTF-8, the standard text format for blobs.
+    // Encode WTF String to UTF-8, the standard text format for Blobs.
     StringUTF8Adaptor utf8_text(plain_text);
     Vector<uint8_t> utf8_bytes;
     utf8_bytes.ReserveInitialCapacity(utf8_text.size());

third_party/blink/renderer/modules/clipboard/clipboard_reader.h

@@ -14,13 +14,27 @@ namespace blink {
 class SystemClipboard;
 class ClipboardPromise;
 
-// Interface for reading async-clipboard-compatible types from the sanitized
+// Interface for reading an individual Clipboard API format from the sanitized
 // System Clipboard as a Blob.
 //
 // Reading a type from the system clipboard to a Blob is accomplished by:
-// (1) Reading the item from the system clipboard.
-// (2) Encoding the blob's contents.
-// (3) Writing the contents to a blob.
+// (1) Reading - the format from the system clipboard.
+// (2) Encoding - the system clipboard's contents for a format. Encoding may be
+//     time-consuming, and so is done on a background thread whenever possible.
+// (3) Writing - the decoded contents to a Blob.
+//
+// ClipboardReader takes as input a ClipboardPromise, from which it expects
+// a clipboard format, and to which it provides a Blob containing an encoded
+// SystemClipboard-originated clipboard payload.
+//
+// Subclasses of ClipboardReader should be implemented for each supported
+// format. Subclasses should:
+// (1) Begin execution by implementing ClipboardReader::Read().
+// (2) Encode the payload on a background thread (if possible) by implementing
+//     a static EncodeOnBackgroundThread() function. This function is called by
+//     Read() via worker_pool::PostTask().
+// (3) Create a Blob and send it to the ClipboardPromise by implementing
+//     ClipboardReader::NextRead().
 class ClipboardReader : public GarbageCollected<ClipboardReader> {
  public:
   // Returns nullptr if there is no implementation for the given mime_type.