Clarify the documentation for loading_only on TabRenderer::UpdateData.

Review URL: http://codereview.chromium.org/63029

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@13256 0039d316-1c4b-4281-b951-d872f2087c98

2 files changed, 16 insertions, 3 deletions

diff --git a/chrome/browser/tabs/tab_strip_model.h b/chrome/browser/tabs/tab_strip_model.h
index 697e59c..8a17b7a 100644
--- a/chrome/browser/tabs/tab_strip_model.h
+++ b/chrome/browser/tabs/tab_strip_model.h
@@ -48,13 +48,16 @@ class TabStripModelObserver {
   virtual void TabInsertedAt(TabContents* contents,
                              int index,
                              bool foreground) { }
+
   // The specified TabContents at |index| is being closed (and eventually
   // destroyed).
   virtual void TabClosingAt(TabContents* contents, int index) { }
+
   // The specified TabContents at |index| is being detached, perhaps to be
   // inserted in another TabStripModel. The implementer should take whatever
   // action is necessary to deal with the TabContents no longer being present.
   virtual void TabDetachedAt(TabContents* contents, int index) { }
+
   // The selected TabContents changed from |old_contents| to |new_contents| at
   // |index|. |user_gesture| specifies whether or not this was done by a user
   // input event (e.g. clicking on a tab, keystroke) or as a side-effect of
@@ -63,15 +66,25 @@ class TabStripModelObserver {
                              TabContents* new_contents,
                              int index,
                              bool user_gesture) { }
+
   // The specified TabContents at |from_index| was moved to |to_index|.
   virtual void TabMoved(TabContents* contents,
                         int from_index,
                         int to_index) { }
+
   // The specified TabContents at |index| changed in some way. |contents| may
   // be an entirely different object and the old value is no longer available
   // by the time this message is delivered.
+  //
+  // If only the loading state was updated, the loading_only flag should be
+  // specified. The tab model will update only the throbber and loading status.
+  // If other things change, set this flag to false to update all state,
+  // including the title and favicon. This allows us to start/stop throbbing
+  // without updating the title (which may be an ugly URL if the real title
+  // hasn't come in yet).
   virtual void TabChangedAt(TabContents* contents, int index,
                             bool loading_only) { }
+
   // The TabStripModel now no longer has any "significant" (user created or
   // user manipulated) tabs. The implementer may use this as a trigger to try
   // and close the window containing the TabStripModel, for example...
diff --git a/chrome/browser/views/tabs/tab_renderer.h b/chrome/browser/views/tabs/tab_renderer.h
index f652843..2f456e4 100644
--- a/chrome/browser/views/tabs/tab_renderer.h
+++ b/chrome/browser/views/tabs/tab_renderer.h
@@ -37,9 +37,9 @@ class TabRenderer : public views::View,
   virtual ~TabRenderer();
 
   // Updates the data the Tab uses to render itself from the specified
-  // TabContents. If only the loading state was updated, the loading_only flag
-  // should be specified. If other things change, set this flag to false to 
-  // update everything.
+  // TabContents.
+  //
+  // See TabStripModel::TabChangedAt documentation for what loading_only means.
   void UpdateData(TabContents* contents, bool loading_only);
 
   // Updates the display to reflect the contents of this TabRenderer's model.