Use scoped_ptr to document ownership in InstantUnloadHandler.

chrome/browser/instant/instant_unload_handler.h

Index: chrome/browser/instant/instant_unload_handler.h
diff --git a/chrome/browser/instant/instant_unload_handler.h b/chrome/browser/instant/instant_unload_handler.h
index 89562f0bfc0c8a135a31460eb2e0d8883aa71ef2..deaf0b7438368efa239388d9bd74e02d5f167c08 100644
--- a/chrome/browser/instant/instant_unload_handler.h
+++ b/chrome/browser/instant/instant_unload_handler.h
@@ -6,6 +6,7 @@
 #define CHROME_BROWSER_INSTANT_INSTANT_UNLOAD_HANDLER_H_
 
 #include "base/basictypes.h"
+#include "base/memory/scoped_ptr.h"
 #include "base/memory/scoped_vector.h"
 
 class Browser;
@@ -14,29 +15,39 @@ namespace content {
 class WebContents;
 }
 
-// InstantUnloadHandler ensures that the beforeunload and unload handlers are
-// run when using Instant. When the user commits the Instant preview the
-// existing WebContents is passed to RunUnloadListenersOrDestroy(). If the tab
-// has no beforeunload or unload listeners, the tab is deleted; otherwise the
-// beforeunload and unload listeners are executed. If the beforeunload listener
-// shows a dialog the tab is added back to the tabstrip at its original location
-// next to the Instant page.
+// InstantUnloadHandler ensures that it runs the BeforeUnload/Unload Handlers
+// (BUH) of a page if the page is replaced by an Instant overlay.
+//
+// Why is this needed? Say the user is looking at a page P. They then try to
+// navigate to another page Q. Consider what happens with and without Instant:
+//
+// Without Instant: Before the navigation is committed, P's BUH are run. If P's
+// BUH return a string (instead of the default null), the user is prompted to
+// "Stay or Leave?". If the user clicks "Stay", the navigation is cancelled,
+// and the user remains on P.
+//
+// With Instant: The navigation to Q has already happened, since Q is being
+// shown as a preview (overlay). When the user "commits" the overlay, it's too
+// late to cancel Q based on P's BUH. So, Instant just replaces P with Q and
+// passes P to InstantUnloadHandler::RunUnloadListenersOrDestroy(). This class
+// runs P's BUH in the background. If the "Stay or Leave?" dialog needs to be
+// shown, it adds P back onto the tabstrip, next to Q. Otherwise, P is deleted.
 class InstantUnloadHandler {
  public:
   explicit InstantUnloadHandler(Browser* browser);
   ~InstantUnloadHandler();
 
   // See class description for details on what this does.
-  void RunUnloadListenersOrDestroy(content::WebContents* contents, int index);
+  void RunUnloadListenersOrDestroy(scoped_ptr<content::WebContents> contents,
+                                   int index);
 
  private:
   class WebContentsDelegateImpl;
 
   // Invoked if the tab is to be shown, at |index| on the tab strip. This
-  // happens if the before unload listener returns a string. Takes ownership of
-  // |delegate| and |contents|.
+  // happens if the beforeunload listener returns a string.
   void Activate(WebContentsDelegateImpl* delegate,
-                content::WebContents* contents,
+                scoped_ptr<content::WebContents> contents,
                 int index);
 
   // Destroys the old tab. This is invoked if script tries to close the page.