Add class comments for ResourceRequest and ResourceResponse

Bug: 740070
Change-Id: I62e54dd3bad45348369007466e4a2dc777aebbba
NoTry: true
Reviewed-on: https://chromium-review.googlesource.com/569938
Commit-Queue: Yutaka Hirano <yhirano@chromium.org>
Reviewed-by: Hiroshige Hayashizaki <hiroshige@chromium.org>
Reviewed-by: Takeshi Yoshino <tyoshino@chromium.org>
Cr-Commit-Position: refs/heads/master@{#486578}

third_party/WebKit/Source/platform/loader/fetch/ResourceRequest.h

@@ -62,6 +62,16 @@ enum InputToLoadPerfMetricReportPolicy : uint8_t {
 
 struct CrossThreadResourceRequestData;
 
+// A ResourceRequest is a "request" object for ResourceLoader. Conceptually
+// it is https://fetch.spec.whatwg.org/#concept-request, but it contains
+// a lot of blink specific fields. WebURLRequest is the "public version"
+// of this class and WebURLLoader needs it. See WebURLRequest and
+// WrappedResourceRequest.
+//
+// There are cases where we need to copy a request across threads, and
+// CrossThreadResourceRequestData is a struct for the purpose. When you add a
+// member variable to this class, do not forget to add the corresponding
+// one in CrossThreadResourceRequestData and write copying logic.
 class PLATFORM_EXPORT ResourceRequest final {
   DISALLOW_NEW();
 
@@ -381,6 +391,14 @@ class PLATFORM_EXPORT ResourceRequest final {
   double navigation_start_ = 0;
 };
 
+// This class is needed to copy a ResourceRequest across threads, because it
+// has some members which cannot be transferred across threads (AtomicString
+// for example).
+// There are some rules / restrictions:
+//  - This struct cannot contain an object that cannot be transferred across
+//    threads (e.g., AtomicString)
+//  - Non-simple members need explicit copying (e.g., String::IsolatedCopy,
+//    KURL::Copy) rather than the copy constructor or the assignment operator.
 struct CrossThreadResourceRequestData {
   WTF_MAKE_NONCOPYABLE(CrossThreadResourceRequestData);
   USING_FAST_MALLOC(CrossThreadResourceRequestData);

third_party/WebKit/Source/platform/loader/fetch/ResourceResponse.h

@@ -46,6 +46,15 @@ namespace blink {
 
 struct CrossThreadResourceResponseData;
 
+// A ResourceResponse is a "response" object used in blink. Conceptually
+// it is https://fetch.spec.whatwg.org/#concept-response, but it contains
+// a lot of blink specific fields. WebURLResponse is the "public version"
+// of this class and public classes (i.e., classes in public/platform) use it.
+//
+// There are cases where we need to copy a response across threads, and
+// CrossThreadResourceResponseData is a struct for the purpose. When you add a
+// member variable to this class, do not forget to add the corresponding
+// one in CrossThreadResourceResponseData and write copying logic.
 class PLATFORM_EXPORT ResourceResponse final {
   DISALLOW_NEW_EXCEPT_PLACEMENT_NEW();
 
@@ -530,6 +539,14 @@ inline bool operator!=(const ResourceResponse& a, const ResourceResponse& b) {
   return !(a == b);
 }
 
+// This class is needed to copy a ResourceResponse across threads, because it
+// has some members which cannot be transferred across threads (AtomicString
+// for example).
+// There are some rules / restrictions:
+//  - This struct cannot contain an object that cannot be transferred across
+//    threads (e.g., AtomicString)
+//  - Non-simple members need explicit copying (e.g., String::IsolatedCopy,
+//    KURL::Copy) rather than the copy constructor or the assignment operator.
 struct CrossThreadResourceResponseData {
   WTF_MAKE_NONCOPYABLE(CrossThreadResourceResponseData);
   USING_FAST_MALLOC(CrossThreadResourceResponseData);