Put history insertion for downloads processing inline.

chrome/browser/download/download_item.cc

Index: chrome/browser/download/download_item.cc
diff --git a/chrome/browser/download/download_item.cc b/chrome/browser/download/download_item.cc
index f6bee14b83bd482addfac21ec8bc31f49451465d..2561c3702594baf3772c7cda032769128b419cf6 100644
--- a/chrome/browser/download/download_item.cc
+++ b/chrome/browser/download/download_item.cc
@@ -27,6 +27,44 @@
 #include "chrome/common/extensions/extension.h"
 #include "chrome/common/pref_names.h"
 
+// The lifecycle of a DownloadItem under normal conditions:

[Paweł Hajdan Jr., 2011/01/03 09:43:03]

I'm not sure if it's a good idea to put all that info in a comment. It's very
likely to get outdated and increase confusion.

[Randy Smith (Not in Mondays), 2011/01/04 19:29:21]

Fair enough.  Long term I really feel like there needs to be more documentation
on the lifecycle of a download item, but this is probably too much.  Let me know
what you think of my much shorter version.

+//      * Created.  Downloading of data starts here.
+//        (DownloadFileManager::StartDownload ->
+//         DownloadManager::CreateDownloadItem).
+//      * Made visible to consumers by entry into
+//        DownloadManager::in_progress_ map after file information is
+//        nailed down.  The file into which data
+//        is being downloaded is renamed to the intermedate file name here (*)
+//        (DownloadManager::OnPathExistenceAvailable (or select file callback)
+//        -> DownloadManager::AttachDownloadItem).
+//      * Entered into the downloads history
+//        (HistoryBackEnd::CreateDownload)
+//      * Made visible in the download shelf
+//        (DownloadManager::OnCreateDownloadEntryComplete after entry into
+//        history).
+//      * Completed--after above sequence and all data has been received.
+//        (DownloadManager::MaybeCompleteDownload).
+//      * Renamed to final name (*) and possibly auto-opened
+//        (DownloadManager::DownloadFinished -> platform_util::OpenItem)
+//
+// (*) Both the nature of the intermediate file name and the routines used
+// for immedate and final file rename are different for dangerous and
+// non-dangerous downloads:
+//      * Non-dangerous: Intermediate file format "<actual name>.crdownload"
+//        (with a possible path uniquifier).  Intermediate file rename done
+//        by DownloadFileManager::OnIntermediateDownloadName,  Final file
+//        rename done by DownloadFileManager::OnFinalDownloadName.
+//      * Dangerous: Intermediate file format "unconfirmed %d.crdownload".
+//        Intermediate file rename done by
+//        DownloadFileManager::OnFinalDownloadName (sic).  Final file
+//        rename done by DownloadManager::ProceedWithDangerousDownload.
+
+// TODO(rdsmith): This progress should be reflected in
+// DownloadItem::DownloadState and a state transition table/state diagram.
+//
+// TODO(rdsmith): This description should be updated to reflect the cancel
+// pathways.
+
 namespace {
 
 // Update frequency (milliseconds).