Fix utterly wrong comment that hasn't been true for years.

content/public/browser/navigation_controller.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 CONTENT_PUBLIC_BROWSER_NAVIGATION_CONTROLLER_H_
 #define CONTENT_PUBLIC_BROWSER_NAVIGATION_CONTROLLER_H_
 #pragma once
 
 #include <string>
 #include <vector>
 
 #include "base/string16.h"
 #include "content/common/content_export.h"
 #include "content/public/browser/global_request_id.h"
 #include "content/public/common/page_transition_types.h"
 
 class GURL;
 
 namespace content {
 
 class BrowserContext;
 class NavigationEntry;
 class SessionStorageNamespace;
 class WebContents;
 struct Referrer;
 
-// A NavigationController maintains the back-forward list for a single tab and
+// A NavigationController maintains the back-forward list for a WebContents and
 // manages all navigation within that list.
 //
-// The NavigationController also owns all WebContents for the tab. This is to
-// make sure that we have at most one WebContents instance per type.
+// Each NavigationController belongs to one WebContents; each WebContents has
+// exactly one NavigationController.
 class NavigationController {
  public:
   enum ReloadType {
     NO_RELOAD,                // Normal load.
     RELOAD,                   // Normal (cache-validating) reload.
     RELOAD_IGNORING_CACHE     // Reload bypassing the cache, aka shift-reload.
   };
 
-  // Creates navigation entry and translates the virtual url to a real one.
-  // Used when navigating to a new URL using LoadURL.  Extra headers are
-  // separated by \n.
+  // Creates a navigation entry and translates the virtual url to a real one.
+  // This is a general call; prefer LoadURL[FromRenderer]/TransferURL below.
+  // Extra headers are separated by \n.
   CONTENT_EXPORT static NavigationEntry* CreateNavigationEntry(
       const GURL& url,
       const Referrer& referrer,
       PageTransition transition,
       bool is_renderer_initiated,
       const std::string& extra_headers,
       BrowserContext* browser_context);
 
   // Disables checking for a repost and prompting the user. This is used during
   // testing.
   CONTENT_EXPORT static void DisablePromptOnRepost();
 
   virtual ~NavigationController() {}
 
-  // Returns the web contents associated with this controller. Non-NULL except
-  // during set-up of the tab.
+  // Returns the web contents associated with this controller. It can never be
+  // NULL.
   virtual WebContents* GetWebContents() const = 0;
 
   // Get/set the browser context for this controller. It can never be NULL.
   virtual BrowserContext* GetBrowserContext() const = 0;
   virtual void SetBrowserContext(BrowserContext* browser_context) = 0;
 
   // Initializes this NavigationController with the given saved navigations,
   // using selected_navigation as the currently loaded entry. Before this call
   // the controller should be unused (there should be no current entry). If
   // from_last_session is true, navigations are from the previous session,
   // otherwise they are from the current session (undo tab close). This takes
   // ownership of the NavigationEntrys in |entries| and clears it out.
   // This is used for session restore.
   virtual void Restore(int selected_navigation,
                        bool from_last_session,
                        std::vector<NavigationEntry*>* entries) = 0;
 
+  // Entries -------------------------------------------------------------------
+
+  // There are two basic states for entries: pending and committed. When an
+  // entry is navigated to, a request is sent to the server. While that request
+  // has not been responded to, the NavigationEntry is pending. Once data is
+  // received for that entry, that NavigationEntry is committed.
+
+  // A transient entry is an entry that, when the user navigates away, is
+  // removed and discarded rather than being added to the back-forward list.
+  // Transient entries are useful for interstitial pages and the like.
+
   // Active entry --------------------------------------------------------------
 
   // Returns the active entry, which is the transient entry if any, the pending
   // entry if a navigation is in progress or the last committed entry otherwise.
   // NOTE: This can be NULL!!
   //
   // If you are trying to get the current state of the NavigationController,
   // this is the method you will typically want to call.  If you want to display
   // the active entry to the user (e.g., in the location bar), use
   // GetVisibleEntry instead.
@@ skipping 163 matching lines @@
   virtual void CopyStateFromAndPrune(NavigationController* source) = 0;
 
   // Removes all the entries except the active entry. If there is a new pending
   // navigation it is preserved.
   virtual void PruneAllButActive() = 0;
 };
 
 }  // namespace content
 
 #endif  // CONTENT_PUBLIC_BROWSER_NAVIGATION_CONTROLLER_H_