src: update and expand comments in base-object.h

It's safe to call BaseObject::object() from your destructor _unless_
the handle is weak; then it's the weak callback that is calling your
destructor and the object will have been released by the time the
destructor runs.

Reviewed-by: Trevor Norris <trev.norris@gmail.com>

1 files changed, 7 insertions, 2 deletions

diff --git a/src/base-object.h b/src/base-object.h
index 3a18a4fde4..0e0df3e938 100644
--- a/src/base-object.h
+++ b/src/base-object.h
@@ -32,10 +32,15 @@ class BaseObject {
   BaseObject(Environment* env, v8::Local<v8::Object> handle);
   ~BaseObject();
 
-  // Returns the wrapped object.  Illegal to call in your destructor.
+  // Returns the wrapped object.  Returns an empty handle when
+  // persistent.IsEmpty() is true.
   inline v8::Local<v8::Object> object();
 
-  // Parent class is responsible to Dispose.
+  // The parent class is responsible for calling .Reset() on destruction
+  // when the persistent handle is strong because there is no way for
+  // BaseObject to know when the handle goes out of scope.
+  // Weak handles have been reset by the time the destructor runs but
+  // calling .Reset() again is harmless.
   inline v8::Persistent<v8::Object>& persistent();
 
   inline Environment* env() const;