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

net/disk_cache/disk_cache.h

Index: net/disk_cache/disk_cache.h
===================================================================
--- net/disk_cache/disk_cache.h	(revision 175363)
+++ net/disk_cache/disk_cache.h	(working copy)
@@ -127,7 +127,12 @@
   // 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;