Rearrange Should*Download delegate calls to be more useful and intuitive.

content/public/browser/download_manager_delegate.h

 // Copyright (c) 2011 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 CONTENT_PUBLIC_BROWSER_DOWNLOAD_MANAGER_DELEGATE_H_
 #define CONTENT_PUBLIC_BROWSER_DOWNLOAD_MANAGER_DELEGATE_H_
 #pragma once
 
 #include "base/basictypes.h"
 #include "base/memory/weak_ptr.h"
@@ skipping 33 matching lines @@
                                         FilePath* intermediate_path) = 0;
 
   // Called when the download system wants to alert a TabContents that a
   // download has started, but the TabConetnts has gone away. This lets an
   // delegate return an alternative TabContents. The delegate can return NULL.
   virtual TabContents* GetAlternativeTabContentsToNotifyForDownload() = 0;
 
   // Tests if a file type should be opened automatically.
   virtual bool ShouldOpenFileBasedOnExtension(const FilePath& path) = 0;
 
-  // Allows the delegate to override the opening of a download. If it returns
-  // true then it's reponsible for opening the item.
+  // Allows the delegate to override completion of the download.  If this
+  // function returns false, the download completion is delayed and the
+  // delegate is responsible for making sure that
+  // DownloadManager::MaybeCompleteDownload is called at some point in the
+  // future.  Note that at that point this function will be called again,
+  // and is responsible for returning true when it really is ok for the
+  // download to complete.
+  virtual bool ShouldCompleteDownload(DownloadItem* item) = 0;
+
+  // Allows the delegate to override opening the download. If this function
+  // returns false, the delegate needs to call
+  // DownloadItem::DelayedDownloadOpened when it's done with the item,
+  // and is responsible for opening it.  This function is called
+  // after the final rename, but before the download state is set to COMPLETED.
   virtual bool ShouldOpenDownload(DownloadItem* item) = 0;
 
-  // Allows the delegate to override completing the download. The delegate needs
-  // to call DownloadItem::CompleteDelayedDownload when it's done with the item,
-  // and is responsible for opening it.
-  virtual bool ShouldCompleteDownload(DownloadItem* item) = 0;
-
   // Returns true if we need to generate a binary hash for downloads.
   virtual bool GenerateFileHash() = 0;
 
   // Informs the delegate that given download has finishd downloading, and gives
   // it the hash (if it chose to compute it from GenerateFileHash()).
   virtual void OnResponseCompleted(DownloadItem* item,
                                    const std::string& hash) = 0;
 
   // Notifies the delegate that a new download item is created. The
   // DownloadManager waits for the delegate to add information about this
@@ skipping 38 matching lines @@
 
  protected:
   DownloadManagerDelegate() {}
 
   DISALLOW_COPY_AND_ASSIGN(DownloadManagerDelegate);
 };
 
 }  // namespace content
 
 #endif  // CONTENT_PUBLIC_BROWSER_DOWNLOAD_MANAGER_DELEGATE_H_