Disk cache: Improve the documentation related to proper use of enumerations. (issue 11848003)

[rva...@chromium.org]

Reviewers: gavinp,

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

BUG=168870
TEST=none

Please review this at https://codereview.chromium.org/11848003/

SVN Base: svn://svn.chromium.org/chrome/trunk/src/

Affected files:
M 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.
virtual int OpenNextEntry(void** iter, Entry** next_entry,
const CompletionCallback& callback) = 0;

[gav...@chromium.org]

LGTM. The nit is really take it or leave it.


https://codereview.chromium.org/11848003/diff/1/net/disk_cache/disk_cache.h
File net/disk_cache/disk_cache.h (right):

https://codereview.chromium.org/11848003/diff/1/net/disk_cache/disk_cache.h#newcode135
net/disk_cache/disk_cache.h:135: // may result in loops in the

enumeration, skipped entries or similar.

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.

https://codereview.chromium.org/11848003/