Reporting: Clarify "pending" reports, add README.md.

net/reporting/reporting_cache.h

 // Copyright 2017 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 NET_REPORTING_REPORTING_CACHE_H_
 #define NET_REPORTING_REPORTING_CACHE_H_
 
 #include <map>
 #include <memory>
 #include <string>
@@ skipping 13 matching lines @@
 namespace net {
 
 struct ReportingReport;
 
 // The cache holds undelivered reports and clients (per-origin endpoint
 // configurations) in memory. (It is not responsible for persisting them.)
 //
 // This corresponds roughly to the "Reporting cache" in the spec, except that
 // endpoints and clients are stored in a more structurally-convenient way, and
 // endpoint failures/retry-after are tracked in ReportingEndpointManager.
+//
+// The cache implementation has the notion of "pending" reports. These are
+// reports that are part of an active delivery attempt, so they won't be
+// actually deallocated. Any attempt to remove a pending report wil mark it
+// "doomed", which will cause it to be deallocated once it is no longer pending.
 class NET_EXPORT ReportingCache {
  public:
   ReportingCache();
 
   ~ReportingCache();
 
   // Adds a report to the cache.
   //
   // All parameters correspond to the desired values for the relevant fields in
   // ReportingReport.
@@ skipping 113 matching lines @@
   // Reports that have been marked "doomed" (would have been deleted, but were
   // pending when the deletion was requested).
   std::unordered_set<const ReportingReport*> doomed_reports_;
 
   DISALLOW_COPY_AND_ASSIGN(ReportingCache);
 };
 
 }  // namespace net
 
 #endif  // NET_REPORTING_REPORTING_CACHE_H_