Add some words of caution to File::Flush().

base/files/file.h

Index: base/files/file.h
diff --git a/base/files/file.h b/base/files/file.h
index 43ef3547a10d4ed88754059d687fe634dfd2e032..885e00b95776d1030c503bd03ffdb2222af1f9d4 100644
--- a/base/files/file.h
+++ b/base/files/file.h
@@ -252,6 +252,16 @@ class BASE_EXPORT File {
 
   // Instructs the filesystem to flush the file to disk. (POSIX: fsync, Windows:
   // FlushFileBuffers).
+  // Calling Flush() does not guarantee file integrity and thus is not a valid
+  // substitute for file integrity checks and recovery codepaths for malformed
+  // files. It can also be *really* slow, so avoid blocking on Flush(),
+  // especially please don't block shutdown on Flush().
+  // Latency percentiles of Flush() across all platforms as of July 2016:
+  // 50 %     > 5 ms
+  // 10 %     > 58 ms
+  //  1 %     > 357 ms
+  //  0.1 %   > 1.8 seconds
+  //  0.01 %  > 7.6 seconds
   bool Flush();
 
   // Updates the file times.
@@ -310,10 +320,6 @@ class BASE_EXPORT File {
   // traversal ('..') components.
   void DoInitialize(const FilePath& path, uint32_t flags);
 
-  // TODO(tnagel): Reintegrate into Flush() once histogram isn't needed anymore,
-  // cf. issue 473337.
-  bool DoFlush();
-
   void SetPlatformFile(PlatformFile file);
 
 #if defined(OS_WIN)