Add comments to SimpleSynchronousEntry callbacks.

net/disk_cache/simple/simple_synchronous_entry.h

 // Copyright (c) 2013 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_DISK_CACHE_SIMPLE_SIMPLE_SYNCHRONOUS_ENTRY_H_
 #define NET_DISK_CACHE_SIMPLE_SIMPLE_SYNCHRONOUS_ENTRY_H_
 
 #include <string>
 
 #include "base/callback_forward.h"
 #include "base/files/file_path.h"
 #include "base/memory/ref_counted.h"
 #include "base/platform_file.h"
 #include "base/task_runner.h"
 #include "base/time.h"
 #include "net/base/completion_callback.h"
 #include "net/disk_cache/simple/simple_disk_format.h"
 
 namespace base {
 class SingleThreadTaskRunner;
 }
 
 namespace net {
 class IOBuffer;
 }
 
 namespace disk_cache {
 
 // Worker thread interface to the very simple cache. This interface is not
 // thread safe, and callers must insure that it is only ever accessed from

[pasko-google - do not use, 2013/04/08 09:25:13]

s/insure/ensure/

??

[gavinp, 2013/04/08 11:26:03]

Both words are valid, see
http://www.ahdictionary.com/word/search.html?id=A5502000 .

Ensure has the narrower meaning. I'm doing the change. Done.

 // a single thread between synchronization points.
 class SimpleSynchronousEntry {
  public:
-  typedef base::Callback<void(SimpleSynchronousEntry*)>
+  // Callback type for the completion of creation of SimpleSynchronousEntry
+  // objects, for instance after OpenEntry() or CreateEntry(). |new_entry| is
+  // the newly created SimpleSynchronousEntry, constructed on the worker pool
+  // thread. |new_entry| == NULL in the case of error.
+  typedef base::Callback<void(SimpleSynchronousEntry* /* new_entry */)>
       SynchronousCreationCallback;
 
-  typedef base::Callback<void(int)>
-      SynchronousOperationCallback;
+  // Callback type for IO operations on an entry not requiring special callback
+  // arguments (e.g. Write). |result| is a net::Error result code.
+  typedef base::Callback<void(int /* result */)> SynchronousOperationCallback;
 
   static void OpenEntry(
       const base::FilePath& path,
       const std::string& key,
       const scoped_refptr<base::TaskRunner>& callback_runner,
       const SynchronousCreationCallback& callback);
 
   static void CreateEntry(
       const base::FilePath& path,
       const std::string& key,
@@ skipping 54 matching lines @@
   base::Time last_used_;
   base::Time last_modified_;
   int32 data_size_[kSimpleEntryFileCount];
 
   base::PlatformFile files_[kSimpleEntryFileCount];
 };
 
 }  // namespace disk_cache
 
 #endif  // NET_DISK_CACHE_SIMPLE_SIMPLE_SYNCHRONOUS_ENTRY_H_