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..5e85244ab42da6e9aea9ef3419b1b50d014f0615 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() {}
@@ -131,9 +130,10 @@ class PageLoadMetricsObserver {
 
   // OnTimingUpdate is triggered when an updated PageLoadTiming is

[Charlie Harrison, 2016/07/15 13:01:17]

Can you include a comment that none of the On* callbacks will be called for non
tracked pages? OnComplete is not important for a big chunk of observers.

[Bryan McQuade, 2016/07/15 14:14:43]

Good point, yes, I re-ordered the callbacks and added a comment to note which
callbacks won't be invoked for untracked pages.

   // 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.
+  // 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) {}
 
@@ -149,9 +149,10 @@ class PageLoadMetricsObserver {
   // 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.
+  // data collected over the course of the page load. OnComplete will not be
+  // called for page loads that did not meet the criteria for tracking metrics
+  // at the time the navigation committed. After this call, the object will be
+  // deleted.
   virtual void OnComplete(const PageLoadTiming& timing,
                           const PageLoadExtraInfo& extra_info) {}