ntp_snippets cleanup: Update some interface comments

components/ntp_snippets/content_suggestions_service.h

 // Copyright 2016 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 COMPONENTS_NTP_SNIPPETS_CONTENT_SUGGESTIONS_SERVICE_H_
 #define COMPONENTS_NTP_SNIPPETS_CONTENT_SUGGESTIONS_SERVICE_H_
 
 #include <map>
 #include <memory>
 #include <set>
@@ skipping 32 matching lines @@
                                   public history::HistoryServiceObserver {
  public:
   class Observer {
    public:
     // Fired every time the service receives a new set of data for the given
     // |category|, replacing any previously available data (though in most cases
     // there will be an overlap and only a few changes within the data). The new
     // data is then available through |GetSuggestionsForCategory(category)|.
     virtual void OnNewSuggestions(Category category) = 0;
 
-    // Fired when the status of a suggestions category changed. When the status
-    // changes to an unavailable status, the suggestions of the respective
-    // category have been invalidated, which means that they must no longer be
-    // displayed to the user. The UI must immediately clear any suggestions of
-    // that category.
+    // Fired when the status of a suggestions category changed. Note that for
+    // some status changes, the UI must update immediately (e.g. to remove
+    // invalidated suggestions). See comments on the individual CategoryStatus
+    // values for details.
     virtual void OnCategoryStatusChanged(Category category,
                                          CategoryStatus new_status) = 0;
 
     // Fired when a suggestion has been invalidated. The UI must immediately
     // clear the suggestion even from open NTPs. Invalidation happens, for
     // example, when the content that the suggestion refers to is gone.
     // Note that this event may be fired even if the corresponding category is
     // not currently AVAILABLE, because open UIs may still be showing the
     // suggestion that is to be removed. This event may also be fired for
     // |suggestion_id|s that never existed and should be ignored in that case.
@@ skipping 283 matching lines @@
 
   // Provides order for categories.
   std::unique_ptr<CategoryRanker> category_ranker_;
 
   DISALLOW_COPY_AND_ASSIGN(ContentSuggestionsService);
 };
 
 }  // namespace ntp_snippets
 
 #endif  // COMPONENTS_NTP_SNIPPETS_CONTENT_SUGGESTIONS_SERVICE_H_