Split V8Proxy::retrieveActiveFrame() into two methods.

webkit/glue/webframe.h

 // Copyright (c) 2006-2009 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef WEBKIT_GLUE_WEBFRAME_H_
 #define WEBKIT_GLUE_WEBFRAME_H_
 
 #include "base/scoped_ptr.h"
 #include "googleurl/src/gurl.h"
 #include "skia/ext/bitmap_platform_device.h"
@@ skipping 14 matching lines @@
 struct WebScriptSource;
 struct WebSize;
 }
 
 // Every frame in a web page is represented by one WebFrame, including the
 // outermost frame.
 class WebFrame {
  public:
   WebFrame() {}
 
-  static WebFrame* RetrieveActiveFrame();
+  // The two functions below retrieve WebFrame instances relating the currently
+  // executing JavaScript. Since JavaScript can make function calls across
+  // frames, though, we need to be more precise.
+  //
+  // For example, imagine that a JS function in frame A calls a function in
+  // frame B, which calls native code, which wants to know what the 'active'
+  // frame is.
+  //
+  // The 'entered context' is the context where execution first entered the
+  // script engine; the context that is at the bottom of the JS function stack.
+  // RetrieveFrameForEnteredContext() would return Frame A in our example.
+  //
+  // The 'current context' is the context the JS engine is currently inside of;
+  // the context that is at the top of the JS function stack.
+  // RetrieveFrameForCurrentContext() would return Frame B in our example.
+  static WebFrame* RetrieveFrameForEnteredContext();
+  static WebFrame* RetrieveFrameForCurrentContext();
 
   // Binds a C++ class to a JavaScript property of the window object.  This
   // should generally be used via CppBoundClass::BindToJavascript() instead of
   // calling it directly.
   virtual void BindToWindowObject(const std::wstring& name,
                                   NPObject* object) = 0;
 
   virtual void CallJSGC() = 0;
 
   // WARNING: DON'T USE THIS METHOD unless you know what it is doing.
@@ skipping 352 matching lines @@
   virtual int PendingFrameUnloadEventCount() const = 0;
 
  protected:
   virtual ~WebFrame() {}
 
  private:
   DISALLOW_COPY_AND_ASSIGN(WebFrame);
 };
 
 #endif  // WEBKIT_GLUE_WEBFRAME_H_