Cleanup: Updating FileSystemFileUtil comments

webkit/fileapi/file_system_file_util.h

 // Copyright (c) 2012 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 WEBKIT_FILEAPI_FILE_SYSTEM_FILE_UTIL_H_
 #define WEBKIT_FILEAPI_FILE_SYSTEM_FILE_UTIL_H_
 
 #include "base/file_path.h"
 #include "base/file_util_proxy.h"
 #include "base/platform_file.h"
 #include "webkit/fileapi/file_system_path.h"
 
 namespace base {
 class Time;
 }
 
 namespace fileapi {
 
 using base::PlatformFile;
 using base::PlatformFileError;
 class FileSystemOperationContext;
 
-// A large part of this implementation is taken from base::FileUtilProxy.
+// A file utility interface that provides basic file utility methods for
+// FileSystem API.
 //
-// The default implementations of the virtual methods below (*1) assume the
-// given paths are native ones for the host platform.  The subclasses that
-// perform local path translation/obfuscation must override them.
-//  (*1) All virtual methods which receive FilePath as their arguments:
-//  CreateOrOpen, EnsureFileExists, GetLocalFilePath, GetFileInfo,
-//  ReadDirectory, CreateDirectory, CopyOrMoveFile, DeleteFile,
-//  DeleteSingleDirectory, Touch, Truncate, PathExists, DirectoryExists,
-//  IsDirectoryEmpty and CreateFileEnumerator.
-//
-// The methods below (*2) assume the given paths may not be native ones for the
-// host platform.  The subclasses should not override them.  They provide basic
-// meta logic by using other virtual methods.
-//  (*2) All non-virtual methods: Copy, Move, Delete, DeleteDirectoryRecursive,
-//  PerformCommonCheckAndPreparationForMoveAndCopy and CopyOrMoveDirectory.
+// TODO(kinuko): Move all the default implementation out of this class
+// and make this class pure abstract class.
 class FileSystemFileUtil {
  public:
   // It will be implemented by each subclass such as FileSystemFileEnumerator.
   class AbstractFileEnumerator {
    public:
     virtual ~AbstractFileEnumerator() {}
 
     // Returns an empty string if there are no more results.
     virtual FilePath Next() = 0;
 
@@ skipping 11 matching lines @@
 
   // Deletes a file or a directory.
   // It is an error to delete a non-empty directory with recursive=false.
   //
   // This method calls one of the following methods depending on whether the
   // target is a directory or not, and whether the |recursive| flag is given or
   // not.
   // - (virtual) DeleteFile,
   // - (virtual) DeleteSingleDirectory or
   // - (non-virtual) DeleteDirectoryRecursive which calls two methods above.
+  //
+  // TODO(kinuko): Move this implementation outside FileSystemFileUtil.
   PlatformFileError Delete(
       FileSystemOperationContext* context,
       const FileSystemPath& path,
       bool recursive);
 
   // Creates or opens a file with the given flags.
   // If PLATFORM_FILE_CREATE is set in |file_flags| it always tries to create
   // a new file at the given |path| and calls back with
   // PLATFORM_FILE_ERROR_FILE_EXISTS if the |path| already exists.
   virtual PlatformFileError CreateOrOpen(
@@ skipping 54 matching lines @@
       const FileSystemPath& root_path);
 
   // Maps |virtual_path| given |context| into |local_file_path| which represents
   // physical file location on the host OS.
   // This may not always make sense for all subclasses.
   virtual PlatformFileError GetLocalFilePath(
       FileSystemOperationContext* context,
       const FileSystemPath& file_system_path,
       FilePath* local_file_path);
 
-  // Touches a file.
-  // If the file doesn't exist, this fails with PLATFORM_FILE_ERROR_NOT_FOUND.
+  // Updates the file metadata information.  Unlike posix's touch, it does
+  // not create a file even if |path| does not exist, but instead fails
+  // with PLATFORM_FILE_ERROR_NOT_FOUND.
   virtual PlatformFileError Touch(
       FileSystemOperationContext* context,
       const FileSystemPath& path,
       const base::Time& last_access_time,
       const base::Time& last_modified_time);
 
-  // Truncates a file to the given length. If |length| is greater than the
+  // Truncates a file to the given length.  If |length| is greater than the
   // current length of the file, the file will be extended with zeroes.
   virtual PlatformFileError Truncate(
       FileSystemOperationContext* context,
       const FileSystemPath& path,
       int64 length);
 
+  // Returns true if a given |path| exists.
   virtual bool PathExists(
       FileSystemOperationContext* context,
       const FileSystemPath& path);
 
+  // Returns true if a given |path| exists and is a directory.
   virtual bool DirectoryExists(
       FileSystemOperationContext* context,
       const FileSystemPath& path);
 
+  // Returns true if a given |path| is an empty directory.
   virtual bool IsDirectoryEmpty(
       FileSystemOperationContext* context,
       const FileSystemPath& path);
 
+  // Copies or moves a single file from |src_path| to |dest_path|.
   virtual PlatformFileError CopyOrMoveFile(
       FileSystemOperationContext* context,
       const FileSystemPath& src_path,
       const FileSystemPath& dest_path,
       bool copy);
 
   // Copies in a single file from a different filesystem.  The
-  // underlying_src_path is a local path which can be handled by the
+  // |underlying_src_path| is a local path which can be handled by the
   // underlying filesystem.
   virtual PlatformFileError CopyInForeignFile(
         FileSystemOperationContext* context,
         const FileSystemPath& underlying_src_path,
         const FileSystemPath& dest_path);
 
   // Deletes a single file.
   // It assumes the given path points a file.
-  //
-  // This method is called from DeleteDirectoryRecursive and Delete (both are
-  // non-virtual).
   virtual PlatformFileError DeleteFile(
       FileSystemOperationContext* context,
       const FileSystemPath& path);
 
   // Deletes a single empty directory.
   // It assumes the given path points an empty directory.
-  //
-  // This method is called from DeleteDirectoryRecursive and Delete (both are
-  // non-virtual).
   virtual PlatformFileError DeleteSingleDirectory(
       FileSystemOperationContext* context,
       const FileSystemPath& path);
 
  protected:
   FileSystemFileUtil();
   explicit FileSystemFileUtil(FileSystemFileUtil* underlying_file_util);
 
   // Deletes a directory and all entries under the directory.
   //
   // This method is called from Delete.  It internally calls two following
   // virtual methods,
   // - (virtual) DeleteFile to delete files, and
   // - (virtual) DeleteSingleDirectory to delete empty directories after all
   // the files are deleted.
+  //
+  // TODO(kinuko): Move this method out of this class.
   PlatformFileError DeleteDirectoryRecursive(
       FileSystemOperationContext* context,
       const FileSystemPath& path);
 
+  // TODO(kinuko): We should stop FileUtil layering.
   FileSystemFileUtil* underlying_file_util() const {
     return underlying_file_util_.get();
   }
 
  private:
   scoped_ptr<FileSystemFileUtil> underlying_file_util_;
 
   DISALLOW_COPY_AND_ASSIGN(FileSystemFileUtil);
 };
 
 }  // namespace fileapi
 
 #endif  // WEBKIT_FILEAPI_FILE_SYSTEM_FILE_UTIL_H_