Disk cache: Improve the documentation related to proper use of enumerations.

net/disk_cache/disk_cache.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.
 
 // Defines the public interface of the disk cache. For more details see
 // http://dev.chromium.org/developers/design-documents/network-stack/disk-cache
 
 #ifndef NET_DISK_CACHE_DISK_CACHE_H_
 #define NET_DISK_CACHE_DISK_CACHE_H_
 
@@ skipping 109 matching lines @@
   // the first time. That will cause the enumeration to start at the head of
   // the cache. For subsequent calls, pass the same |iter| pointer again without
   // changing its value. This method returns ERR_FAILED when there are no more
   // entries to enumerate. When the entry pointer is no longer needed, its
   // Close method should be called. The return value is a net error code. If
   // this method returns ERR_IO_PENDING, the |callback| will be invoked when the
   // |next_entry| is available. The pointer to receive the |next_entry| must
   // remain valid until the operation completes.
   //
   // NOTE: This method does not modify the last_used field of the entry, and
-  // therefore it does not impact the eviction ranking of the entry.
+  // therefore it does not impact the eviction ranking of the entry. However,
+  // an enumeration will go through all entries on the cache only if the cache
+  // is not modified while the enumeration is taking place. Significantly
+  // altering the entry pointed by |iter| (for example, deleting the entry) will
+  // invalidate |iter|. Performing operations on an entry that modify the entry
+  // may result in loops in the enumeration, skipped entries or similar.

[gavinp, 2013/01/14 15:20:13]

Good to spell this out.

The only nit is the use of "enumeration." I think it could be better to say
"iteration", not out of correctness (both are correct) but just because there's
a language feature enumeration which could be confused here, just slowing down
the reading.

   virtual int OpenNextEntry(void** iter, Entry** next_entry,
                             const CompletionCallback& callback) = 0;
 
   // Releases iter without returning the next entry. Whenever OpenNextEntry()
   // returns true, but the caller is not interested in continuing the
   // enumeration by calling OpenNextEntry() again, the enumeration must be
   // ended by calling this method with iter returned by OpenNextEntry().
   virtual void EndEnumeration(void** iter) = 0;
 
   // Return a list of cache statistics.
@@ skipping 156 matching lines @@
   // Note: This method is deprecated.
   virtual int ReadyForSparseIO(const CompletionCallback& callback) = 0;
 
  protected:
   virtual ~Entry() {}
 };
 
 }  // namespace disk_cache
 
 #endif  // NET_DISK_CACHE_DISK_CACHE_H_