Minor cleanup of FaviconHandler

chrome/browser/favicon/favicon_handler.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.
 
 #ifndef CHROME_BROWSER_FAVICON_FAVICON_HANDLER_H_
 #define CHROME_BROWSER_FAVICON_FAVICON_HANDLER_H_
 
 #include <map>
 
 #include "base/basictypes.h"
@@ skipping 25 matching lines @@
 //
 // FetchFavicon requests the favicon from the favicon service which in turn
 // requests the favicon from the history database. At this point
 // we only know the URL of the page, and not necessarily the url of the
 // favicon. To ensure we handle reloading stale favicons as well as
 // reloading a favicon on page reload we always request the favicon from
 // history regardless of whether the NavigationEntry has a favicon.
 //
 // After the navigation two types of events are delivered (which is
 // first depends upon who is faster): notification from the history
-// db on our request for the favicon (OnFaviconDataForInitialURL),
-// or a message from the renderer giving us the URL of the favicon for
-// the page (SetFaviconURL).
+// db on our request for the favicon
+// (OnFaviconDataForInitialURLFromFaviconService), or a message from the
+// renderer giving us the URL of the favicon for the page (SetFaviconURL).
 // . If the history db has a valid up to date favicon for the page, we update
 //   the NavigationEntry and use the favicon.
 // . When we receive the favicon url if it matches that of the NavigationEntry
 //   and the NavigationEntry's favicon is set, we do nothing (everything is
 //   ok).
 // . On the other hand if the database does not know the favicon for url, or
 //   the favicon is out date, or the URL from the renderer does not match that
 //   NavigationEntry we proceed to DownloadFaviconOrAskHistory. Before we
 //   invoke DownloadFaviconOrAskHistory we wait until we've received both
 //   the favicon url and the callback from history. We wait to ensure we
@@ skipping 69 matching lines @@
   virtual int DownloadFavicon(const GURL& image_url, int max_bitmap_size);
 
   // Ask the favicon from history
   virtual void UpdateFaviconMappingAndFetch(
       const GURL& page_url,
       const GURL& icon_url,
       chrome::IconType icon_type,
       const FaviconService::FaviconResultsCallback& callback,
       base::CancelableTaskTracker* tracker);
 
-  virtual void GetFavicon(
+  virtual void GetFaviconFromFaviconService(
       const GURL& icon_url,
       chrome::IconType icon_type,
       const FaviconService::FaviconResultsCallback& callback,
       base::CancelableTaskTracker* tracker);
 
-  virtual void GetFaviconForURL(
+  virtual void GetFaviconForURLFromFaviconService(
       const GURL& page_url,
       int icon_types,
       const FaviconService::FaviconResultsCallback& callback,
       base::CancelableTaskTracker* tracker);
 
   virtual void SetHistoryFavicons(const GURL& page_url,
                                   const GURL& icon_url,
                                   chrome::IconType icon_type,
                                   const gfx::Image& image);
 
   virtual FaviconService* GetFaviconService();
 
   // Returns true if the favicon should be saved.
   virtual bool ShouldSaveFavicon(const GURL& url);
 
   // Notifies the delegate that the favicon for the active entry was updated.
   // |icon_url_changed| is true if a favicon with a different icon URL has been
   // selected since the previous call to NotifyFaviconUpdated().
   virtual void NotifyFaviconUpdated(bool icon_url_changed);
 
  private:
   friend class TestFaviconHandler; // For testing
 
+  // Represents an in progress download of an image from the renderer.
   struct DownloadRequest {
     DownloadRequest();
     ~DownloadRequest();
 
     DownloadRequest(const GURL& url,
                     const GURL& image_url,
                     chrome::IconType icon_type);
 
     GURL url;
     GURL image_url;
     chrome::IconType icon_type;
   };
 
+  // Used to track a candidate for the favicon.
   struct FaviconCandidate {
     FaviconCandidate();
     ~FaviconCandidate();
 
     FaviconCandidate(const GURL& url,
                      const GURL& image_url,
                      const gfx::Image& image,
                      float score,
                      chrome::IconType icon_type);
 
     GURL url;
     GURL image_url;
     gfx::Image image;
     float score;
     chrome::IconType icon_type;
   };
 
   // See description above class for details.
-  void OnFaviconDataForInitialURL(
+  void OnFaviconDataForInitialURLFromFaviconService(
       const std::vector<chrome::FaviconBitmapResult>& favicon_bitmap_results);
 
   // If the favicon has expired, asks the renderer to download the favicon.
   // Otherwise asks history to update the mapping between page url and icon
   // url with a callback to OnFaviconData when done.
-  void DownloadFaviconOrAskHistory(const GURL& page_url,
-                                   const GURL& icon_url,
-                                   chrome::IconType icon_type);
+  void DownloadFaviconOrAskFaviconService(const GURL& page_url,
+                                          const GURL& icon_url,
+                                          chrome::IconType icon_type);
 
   // See description above class for details.
   void OnFaviconData(
       const std::vector<chrome::FaviconBitmapResult>& favicon_bitmap_results);
 
   // Schedules a download for the specified entry. This adds the request to
   // download_requests_.
   int ScheduleDownload(const GURL& url,
                        const GURL& image_url,
                        chrome::IconType icon_type);
 
   // Updates |favicon_candidate_| and returns true if it is an exact match.
   bool UpdateFaviconCandidate(const GURL& url,
                               const GURL& image_url,
                               const gfx::Image& image,
                               float score,
                               chrome::IconType icon_type);
 
   // Sets the image data for the favicon.
   void SetFavicon(const GURL& url,
                   const GURL& icon_url,
                   const gfx::Image& image,
                   chrome::IconType icon_type);
 
   // Sets the favicon's data on the NavigationEntry.
   // If the WebContents has a delegate, it is invalidated (INVALIDATE_TYPE_TAB).
-  void UpdateFavicon(content::NavigationEntry* entry,
+  void SetFaviconOnNavigationEntry(
+      content::NavigationEntry* entry,
       const std::vector<chrome::FaviconBitmapResult>& favicon_bitmap_results);
-  void UpdateFavicon(content::NavigationEntry* entry,
-                     const GURL& icon_url,
-                     const gfx::Image& image);
+  void SetFaviconOnNavigationEntry(content::NavigationEntry* entry,
+                                   const GURL& icon_url,
+                                   const gfx::Image& image);
 
   // Return the current candidate if any.
   content::FaviconURL* current_candidate() {
-    return (image_urls_.size() > 0) ? &image_urls_[0] : NULL;
+    return (!image_urls_.empty()) ? &image_urls_.front() : NULL;
   }
 
-  // Returns the preferred_icon_size according icon_types_, 0 means no
-  // preference.
+  // Returns the preferred size of the image. 0 means no preference (any size
+  // will do).
   int preferred_icon_size() {
 #if defined(OS_ANDROID)
     return 0;
 #else
     return icon_types_ == chrome::FAVICON ? gfx::kFaviconSize : 0;
 #endif
   }
 
   // Used for FaviconService requests.
   base::CancelableTaskTracker cancelable_task_tracker_;
@@ skipping 22 matching lines @@
 
   // The FaviconBitmapResults from history.
   std::vector<chrome::FaviconBitmapResult> history_results_;
 
   // The Profile associated with this handler.
   Profile* profile_;
 
   // This handler's delegate.
   FaviconHandlerDelegate* delegate_;  // weak
 
-  // Current favicon candidate.
-  FaviconCandidate favicon_candidate_;
+  // Best image we've seen so far.  As images are downloaded from the page they
+  // are stored here. When there is an exact match, or no more images are
+  // available the favicon service and the NavigationEntry are updated (assuming
+  // the image is for a favicon).
+  FaviconCandidate best_favicon_candidate_;
 
   DISALLOW_COPY_AND_ASSIGN(FaviconHandler);
 };
 
 #endif  // CHROME_BROWSER_FAVICON_FAVICON_HANDLER_H_