Make more precise the consumer intended use of GetTargetFullPath()

content/public/browser/download_item.h

 // Copyright (c) 2012 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.
 //
 // Each download is represented by a DownloadItem, and all DownloadItems
 // are owned by the DownloadManager which maintains a global list of all
 // downloads. DownloadItems are created when a user initiates a download,
 // and exist for the duration of the browser life time.
 //
 // Download observers:
@@ skipping 186 matching lines @@
   virtual std::string GetReferrerCharset() const = 0;
   virtual std::string GetRemoteAddress() const = 0;
   virtual bool HasUserGesture() const = 0;
   virtual PageTransition GetTransitionType() const = 0;
   virtual const std::string& GetLastModifiedTime() const = 0;
   virtual const std::string& GetETag() const = 0;
 
   //    Destination State accessors --------------------------------------------
 
   // Full path to the downloaded or downloading file. This is the path to the
-  // physical file, if one exists. Can be empty if the in-progress path hasn't
-  // been determined yet.
+  // physical file, if one exists. It should be considered a hint; changes to
+  // this value and renames of the file on disk are not atomic with each other.
+  // May be empty if the in-progress path hasn't been determined yet.
   virtual const FilePath& GetFullPath() const = 0;
 
   // Target path of an in-progress download. We may be downloading to a
-  // temporary or intermediate file (specified by |current_path_|.  Once the
-  // download completes, we will rename the file to |target_path_|.
+  // temporary or intermediate file (specified by GetFullPath()); this is the
+  // name we will use once the download completes.
+  // May be empty if the target path hasn't yet been determined.
   virtual const FilePath& GetTargetFilePath() const = 0;
 
   // |GetTargetFilePath().BaseName()|
   virtual FilePath GetTargetName() const = 0;
 
   // If the download forced a path rather than requesting name determination,
   // return the path requested.
   virtual const FilePath& GetForcedFilePath() const = 0;
 
   // Returns the user-verified target file path for the download.
@@ skipping 112 matching lines @@
   virtual void SetDisplayName(const FilePath& name) = 0;
 
   // Debug/testing -------------------------------------------------------------
   virtual std::string DebugString(bool verbose) const = 0;
   virtual void MockDownloadOpenForTesting() = 0;
 };
 
 }  // namespace content
 
 #endif  // CONTENT_PUBLIC_BROWSER_DOWNLOAD_ITEM_H_