Standardize which page loads are tracked

components/page_load_metrics/browser/page_load_metrics_observer.h

Index: components/page_load_metrics/browser/page_load_metrics_observer.h
diff --git a/components/page_load_metrics/browser/page_load_metrics_observer.h b/components/page_load_metrics/browser/page_load_metrics_observer.h
index 3b486dcfb5f51382dfbceca90bfc954d90582c0f..1d73ed05dfa0426032cdaadefea9aa17cea7eac5 100644
--- a/components/page_load_metrics/browser/page_load_metrics_observer.h
+++ b/components/page_load_metrics/browser/page_load_metrics_observer.h
@@ -92,8 +92,7 @@ struct PageLoadExtraInfo {
 };
 
 // Interface for PageLoadMetrics observers. All instances of this class are
-// owned by the PageLoadTracker tracking a page load. They will be deleted after
-// calling OnComplete.
+// owned by the PageLoadTracker tracking a page load.
 class PageLoadMetricsObserver {
  public:
   virtual ~PageLoadMetricsObserver() {}
@@ -129,14 +128,6 @@ class PageLoadMetricsObserver {
   virtual void OnFailedProvisionalLoad(
       content::NavigationHandle* navigation_handle) {}
 
-  // OnTimingUpdate is triggered when an updated PageLoadTiming is
-  // available. This method may be called multiple times over the course of the
-  // page load. Note that this is currently an experimental API which may be
-  // removed in the future. Please email loading-dev@chromium.org if you intend
-  // to override this method.
-  virtual void OnTimingUpdate(const PageLoadTiming& timing,
-                              const PageLoadExtraInfo& extra_info) {}
-
   // OnHidden is triggered when a page leaves the foreground. It does not fire
   // when a foreground page is permanently closed; for that, listen to
   // OnComplete instead.
@@ -146,14 +137,19 @@ class PageLoadMetricsObserver {
   // fire when the page first loads; for that, listen for OnStart instead.
   virtual void OnShown() {}
 
-  // OnComplete is triggered when we are ready to record metrics for this page
-  // load. This will happen some time after commit. The PageLoadTiming struct
-  // contains timing data and the PageLoadExtraInfo struct contains other useful
-  // data collected over the course of the page load. If the load did not
-  // receive any timing information, |timing.IsEmpty()| will be true.
-  // After this call, the object will be deleted.
-  virtual void OnComplete(const PageLoadTiming& timing,
-                          const PageLoadExtraInfo& extra_info) {}
+  // The callbacks below are only invoked after a navigation commits, for
+  // tracked page loads. Page loads that don't meet the criteria for being
+  // tracked at the time a navigation commits will not receive any of the
+  // callbacks below.
+
+  // OnTimingUpdate is triggered when an updated PageLoadTiming is
+  // available. This method may be called multiple times over the course of the
+  // page load. This method is currently only intended for use in testing. Most
+  // implementers should implement one of the On* callbacks, such as
+  // OnFirstContentfulPaint or OnDomContentLoadedEventStart. Please email
+  // loading-dev@chromium.org if you intend to override this method.
+  virtual void OnTimingUpdate(const PageLoadTiming& timing,
+                              const PageLoadExtraInfo& extra_info) {}
 
   // OnUserInput is triggered when a new user input is passed in to
   // web_contents. Contains a TimeDelta from navigation start.
@@ -185,6 +181,14 @@ class PageLoadMetricsObserver {
   // behavior_flags.
   virtual void OnLoadingBehaviorObserved(
       const page_load_metrics::PageLoadExtraInfo& extra_info) {}
+
+  // OnComplete is invoked for tracked page loads, immediately before the
+  // observer is deleted.  The PageLoadTiming struct contains timing data and
+  // the PageLoadExtraInfo struct contains other useful data collected over the
+  // course of the page load. Most observers should not need to implement this
+  // method, and should implement the On* timing callbacks instead.
+  virtual void OnComplete(const PageLoadTiming& timing,
+                          const PageLoadExtraInfo& extra_info) {}
 };
 
 }  // namespace page_load_metrics