Add documentation for platform/bindings

This CL adds a README.md explaining the contents of platform/bindings, as well as adds some class level comments to files that were missing them.

BUG=682322

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

third_party/WebKit/Source/platform/bindings/DOMDataStore.h

@@ -46,6 +46,10 @@
 
 namespace blink {
 
+// Holds a DOMWrapperMap specialized to map between ScriptWrappable objects and
+// their wrappers and provides an API to perform common operations with this map
+// and manage wrappers in a single world. Each world (DOMWrapperWorld) holds a
+// single DOMWrapperMap instance to hold wrappers only for that world.
 class DOMDataStore {
   WTF_MAKE_NONCOPYABLE(DOMDataStore);
   USING_FAST_MALLOC(DOMDataStore);

third_party/WebKit/Source/platform/bindings/DOMWrapperMap.h

@@ -42,6 +42,8 @@
 
 namespace blink {
 
+// Maps from C++ objects to their corresponding JavaScript wrappers. See also
+// DOMDataStore.
 template <class KeyType>
 class DOMWrapperMap {
   USING_FAST_MALLOC(DOMWrapperMap);

third_party/WebKit/Source/platform/bindings/README.md

+# Bindings
+
+This directory contains classes and functionality used to implement the V8 bindings layer in Blink. Any reusable bindings components/infrastructure that are independent of `core/` objects (or can be generalized to be independent) should be added to this directory, otherwise they can be kept in `bindings/core/`.
+
+Some of the things you can find here are:
+
+* Functionality to wrap Blink C++ objects with a JavaScript object and maintain wrappers in multiple worlds (see [ScriptWrappable](ScriptWrappable.h), [ActiveScriptWrappable](ActiveScriptWrappable.h))
+* Implementation of wrapper tracing (see [documentation](TraceWrapperReference.md))
+* Important abstractions for script execution (see [ScriptState](ScriptState.h), [V8PerIsolateData](V8PerIsolateData.h), [V8PerContextData](V8PerContextData.h))
+* Utility functions to interface with V8 and convert between V8 and Blink types (see [V8Binding.h](V8Binding.h), [ToV8.h](ToV8.h))

third_party/WebKit/Source/platform/bindings/ScopedPersistent.h

@@ -40,6 +40,10 @@
 
 namespace blink {
 
+// Holds a persistent handle to a V8 object; use ScopedPersistent instead of
+// directly using v8::Persistent. Introducing a (non-weak) ScopedPersistent
+// has a risk of producing memory leaks, ask blink-reviews-bindings@ for a
+// review.
 template <typename T>
 class ScopedPersistent {
   USING_FAST_MALLOC(ScopedPersistent);

third_party/WebKit/Source/platform/bindings/ScriptWrappable.h

@@ -56,7 +56,7 @@ class PLATFORM_EXPORT TraceWrapperBase {
 // JavaScript object (platform object).  ToV8() converts a ScriptWrappable to
 // a v8::Object and toScriptWrappable() converts a v8::Object back to
 // a ScriptWrappable.  v8::Object as platform object is called "wrapper object".
-// The wrapepr object for the main world is stored in ScriptWrappable.  Wrapper
+// The wrapper object for the main world is stored in ScriptWrappable.  Wrapper
 // objects for other worlds are stored in DOMWrapperMap.
 class PLATFORM_EXPORT ScriptWrappable : public TraceWrapperBase {
   WTF_MAKE_NONCOPYABLE(ScriptWrappable);

third_party/WebKit/Source/platform/bindings/SharedPersistent.h

@@ -38,6 +38,9 @@
 
 namespace blink {
 
+// A ref counted version of ScopedPersistent. This class is intended for use by
+// ScriptValue and not for normal use. Consider using ScopedPersistent directly
+// instead.
 template <typename T>
 class SharedPersistent : public RefCounted<SharedPersistent<T>> {
   WTF_MAKE_NONCOPYABLE(SharedPersistent);

third_party/WebKit/Source/bindings/core/v8/TraceWrapperReference.md → third_party/WebKit/Source/platform/bindings/TraceWrapperReference.md

@@ -26,9 +26,9 @@ object should keep alive.
 The following example illustrates these steps:
 
 ```c++
-#include "bindings/core/v8/ScriptWrappable.h"
-#include "bindings/core/v8/TraceWrapperMember.h"
-#include "bindings/core/v8/TraceWrapperV8Reference.h"
+#include "platform/bindings/ScriptWrappable.h"
+#include "platform/bindings/TraceWrapperMember.h"
+#include "platform/bindings/TraceWrapperV8Reference.h"
 
 class SomeDOMObject : public ScriptWrappable {          // (1)
  public:
@@ -81,10 +81,9 @@ The annotations that are required can be found in the following header files.
 Pick the header file depending on what types are needed.
 
 ```c++
-#include "bindings/core/v8/ScriptWrappable.h"
-#include "bindings/core/v8/TraceWrapperBase.h"
-#include "bindings/core/v8/TraceWrapperMember.h"
-#include "bindings/core/v8/TraceWrapperV8Reference.h"
+#include "platform/bindings/ScriptWrappable.h"
+#include "platform/bindings/TraceWrapperMember.h"
+#include "platform/bindings/TraceWrapperV8Reference.h"
 ```
 
 The following example will guide through the modifications that are needed to

third_party/WebKit/Source/platform/bindings/V8DOMWrapper.h

@@ -44,6 +44,8 @@ namespace blink {
 
 struct WrapperTypeInfo;
 
+// Contains utility methods to create wrappers, associate ScriptWrappable
+// objects with wrappers and set fields in wrappers.
 class V8DOMWrapper {
   STATIC_ONLY(V8DOMWrapper);
 

third_party/WebKit/Source/platform/bindings/V8PerContextData.h

@@ -58,6 +58,8 @@ enum V8ContextEmbedderDataField {
       gin::kEmbedderBlink),             // NOLINT(readability/enum_casing)
 };
 
+// Used to hold data that is associated with a single v8::Context object, and
+// has a 1:1 relationship with v8::Context.
 class PLATFORM_EXPORT V8PerContextData final {
   USING_FAST_MALLOC(V8PerContextData);
   WTF_MAKE_NONCOPYABLE(V8PerContextData);

third_party/WebKit/Source/platform/bindings/V8PerIsolateData.h

@@ -52,6 +52,8 @@ struct WrapperTypeInfo;
 
 typedef WTF::Vector<DOMDataStore*> DOMDataStoreList;
 
+// Used to hold data that is associated with a single v8::Isolate object, and
+// has a 1:1 relationship with v8::Isolate.
 class PLATFORM_EXPORT V8PerIsolateData {
   USING_FAST_MALLOC(V8PerIsolateData);
   WTF_MAKE_NONCOPYABLE(V8PerIsolateData);

third_party/WebKit/Source/platform/bindings/V8ValueCache.h

@@ -74,6 +74,11 @@ class StringCacheMapTraits
   static void DisposeWeak(const v8::WeakCallbackInfo<WeakCallbackDataType>&);
 };
 
+// String cache helps convert WTF strings (StringImpl*) into v8 strings by
+// only creating a v8::String for a particular StringImpl* once and caching it
+// for future use. It is held by and can be retrieved from V8PerIsolateData, and
+// is cleared when the isolate is destroyed. Entries are removed from the
+// backing global value map when weak references to the values are collected.
 class PLATFORM_EXPORT StringCache {
   USING_FAST_MALLOC(StringCache);
   WTF_MAKE_NONCOPYABLE(StringCache);

third_party/WebKit/Source/platform/heap/BlinkGCAPIReference.md

@@ -4,7 +4,7 @@ This is a through document for Oilpan API usage.
 If you want to learn the API usage quickly, look at
 [this tutorial](https://docs.google.com/presentation/d/1XPu03ymz8W295mCftEC9KshH9Icxfq81YwIJQzQrvxo/edit#slide=id.p).
 If you're just interested in wrapper tracing,
-see [Wrapper Tracing Reference](../../bindings/core/v8/TraceWrapperReference.md).
+see [Wrapper Tracing Reference](../bindings/TraceWrapperReference.md).
 
 [TOC]