Add documentation for platform/bindings

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

 /*
  * Copyright (C) 2009 Google Inc. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
  * met:
  *
  *     * Redistributions of source code must retain the above copyright
  * notice, this list of conditions and the following disclaimer.
  *     * Redistributions in binary form must reproduce the above
@@ skipping 22 matching lines @@
 
 #include <memory>
 
 #include "platform/bindings/ScriptWrappableVisitor.h"
 #include "platform/wtf/Allocator.h"
 #include "platform/wtf/Noncopyable.h"
 #include "v8/include/v8.h"
 
 namespace blink {
 
+// Holds a persistent handle to a V8 object.

[haraken, 2017/04/29 02:39:11]

Add that:

- developers should use ScopedPersistent instead of using v8::Persistent
directly
- developers must be super careful when introducing a (non-weak)
ScopedPersistent since it has a high risk of producing memory leaks. Ask
blink-reviews-bindings@ for review.

[jbroman, 2017/04/29 04:11:30]

Aside: What does ScopedPersistent do that v8::Global doesn't? Should we
deprecate ScopedPersistent at some point?

[adithyas, 2017/05/01 17:41:16]

Done.

 template <typename T>
 class ScopedPersistent {
   USING_FAST_MALLOC(ScopedPersistent);
   WTF_MAKE_NONCOPYABLE(ScopedPersistent);
 
  public:
   ScopedPersistent() {}
 
   ScopedPersistent(v8::Isolate* isolate, v8::Local<T> handle)
       : handle_(isolate, handle) {}
@@ skipping 46 matching lines @@
 
   ALWAYS_INLINE v8::Persistent<T>& Get() { return handle_; }
 
  private:
   v8::Persistent<T> handle_;
 };
 
 }  // namespace blink
 
 #endif  // ScopedPersistent_h