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

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

BUG=168870
TEST=none
Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=176728

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

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#n...
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.

[gavinp, 2013-01-17 14:18:01]

On 2013/01/14 15:20:13, gavinp wrote:
> 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#n...
> 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.

My nit was bogus. file_util::FileEnumerator exists, therefore this naming in
disk_cache is something I should just get over.

[rvargas (doing something else), 2013-01-17 18:38:58]

On 2013/01/17 14:18:01, gavinp wrote:
> On 2013/01/14 15:20:13, gavinp wrote:
> > 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#n...
> > 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.
> 
> My nit was bogus. file_util::FileEnumerator exists, therefore this naming in
> disk_cache is something I should just get over.

For completeness, I read the nit and said "sure", then went to the code to find
out that the description of the method was to enumerate the entries... so I
changed one of the occurrences of the word in the description to "iterate", to
be less repetitive and clear up any confusion.