Doxygen comments for media/file

Change-Id: Iba142c50efe9eac169f1ebd016035e070865e742

media/file/file.h

@@ -3,8 +3,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file or at
 // https://developers.google.com/open-source/licenses/bsd
-//
-// Defines an abstract file interface.
 
 #ifndef PACKAGER_FILE_FILE_H_
 #define PACKAGER_FILE_FILE_H_
@@ -17,70 +15,76 @@ namespace media {
 
 extern const char* kLocalFilePrefix;
 
+/// Define an abstract file interface.
 class File {
  public:
-  // Open the specified file, or return NULL on error.
+  /// Open the specified file.
-  // This is actually a file factory method, it opens a proper file, e.g.
+  /// This is a file factory method, it opens a proper file automatically
-  // LocalFile, MemFile automatically based on prefix.
+  /// based on prefix, e.g. "file://" for LocalFile.
+  /// @param file_name contains the name of the file to be accessed.
+  /// @param mode contains file access mode. Implementation dependent.
+  /// @return A File pointer on success, false otherwise.
   static File* Open(const char* file_name, const char* mode);
 
-  // Flush() and de-allocate resources associated with this file, and
+  /// Flush() and de-allocate resources associated with this file, and
-  // delete this File object.  THIS IS THE ONE TRUE WAY TO DEALLOCATE
+  /// delete this File object.  THIS IS THE ONE TRUE WAY TO DEALLOCATE
-  // THIS OBJECT.
+  /// THIS OBJECT.
-  // Returns true on success.
+  /// @return true on success. For writable files, returning false MAY
-  // For writable files, returning false MAY INDICATE DATA LOSS.
+  ///         INDICATE DATA LOSS.
   virtual bool Close() = 0;
 
-  // Reads data and returns it in buffer. Returns a value < 0 on error,
+  /// Read data and return it in buffer.
-  // or the number of bytes read otherwise. Returns zero on end-of-file,
+  /// @param[out] buffer points to a block of memory with a size of at least
-  // or if 'length' is zero.
+  ///             @a length bytes.
+  /// @param length indicates number of bytes to be read.
+  /// @return Number of bytes read, or a value < 0 on error.
+  ///         Zero on end-of-file, or if 'length' is zero.
   virtual int64 Read(void* buffer, uint64 length) = 0;
 
-  // Write 'length' bytes from 'buffer', returning the number of bytes
+  /// Write block of data.
-  // that were actually written.  Return < 0 on error.
+  /// @param buffer points to a block of memory with at least @a length bytes.
-  //
+  /// @param length indicates number of bytes to write.
-  // For a file open in append mode (i.e., "a" or "a+"), Write()
+  /// @return Number of bytes written, or a value < 0 on error.
-  // always appends to the end of the file. For files opened in other
-  // write modes (i.e., "w", or "w+"), writes occur at the
-  // current file offset.
   virtual int64 Write(const void* buffer, uint64 length) = 0;
 
-  // Return the size of the file in bytes.
+  /// @return Size of the file in bytes. A return value less than zero
-  // A return value less than zero indicates a problem getting the
+  ///         indicates a problem getting the size.
-  // size.
   virtual int64 Size() = 0;
 
-  // Flushes the file so that recently written data will survive an
+  /// Flush the file so that recently written data will survive an
-  // application crash (but not necessarily an OS crash).  For
+  /// application crash (but not necessarily an OS crash). For
-  // instance, in localfile the data is flushed into the OS but not
+  /// instance, in LocalFile the data is flushed into the OS but not
-  // necessarily to disk.
+  /// necessarily to disk.
+  /// @return true on success, false otherwise.
   virtual bool Flush() = 0;
 
-  // Return whether we're currently at eof.
+  /// @return true if the file reaches eof, false otherwise.
   virtual bool Eof() = 0;
 
-  // Return the file name.
+  /// @return The file name.
   const std::string& file_name() const { return file_name_; }
 
   // ************************************************************
   // * Static Methods: File-on-the-filesystem status
   // ************************************************************
 
-  // Returns the size of a file in bytes, and opens and closes the file
+  /// @return The size of a file in bytes on success, a value < 0 otherwise.
-  // in the process. Returns a value < 0 on failure.
+  ///         The file will be opened and closed in the process.
   static int64 GetFileSize(const char* file_name);
 
-  // Read the file at |file_name| into |contents|, returning true on success.
+  /// Read the file into string.
-  // |contents| should not be NULL.
+  /// @param file_name is the file to be read. It should be a valid file.
+  /// @param contents[out] points to the output string. Should not be NULL.
+  /// @return true on success, false otherwise.
   static bool ReadFileToString(const char* file_name, std::string* contents);
 
  protected:
   explicit File(const std::string& file_name) : file_name_(file_name) {}
-  // Do *not* call the destructor directly (with the "delete" keyword)
+  /// Do *not* call the destructor directly (with the "delete" keyword)
-  // nor use scoped_ptr; instead use Close().
+  /// nor use scoped_ptr; instead use Close().
   virtual ~File() {}
 
-  // Internal open. Should not be used directly.
+  /// Internal open. Should not be used directly.
   virtual bool Open() = 0;
 
  private:

media/file/file_closer.h

@@ -12,7 +12,8 @@
 
 namespace media {
 
-// Use by scoped_ptr to automatically close the file when it goes out of scope.
+/// Used by scoped_ptr to automatically close the file when it goes out of
+/// scope.
 struct FileCloser {
   inline void operator()(File* file) const {
     if (file != NULL && !file->Close()) {

media/file/local_file.cc

@@ -11,14 +11,8 @@
 
 namespace media {
 
-LocalFile::LocalFile(const char* name, const char* mode)
+LocalFile::LocalFile(const char* file_name, const char* mode)
-    : File(name), file_mode_(mode), internal_file_(NULL) {}
+    : File(file_name), file_mode_(mode), internal_file_(NULL) {}
-
-bool LocalFile::Open() {
-  internal_file_ =
-      base::OpenFile(base::FilePath(file_name()), file_mode_.c_str());
-  return (internal_file_ != NULL);
-}
 
 bool LocalFile::Close() {
   bool result = true;
@@ -69,4 +63,12 @@ bool LocalFile::Eof() {
   return static_cast<bool>(feof(internal_file_));
 }
 
+LocalFile::~LocalFile() {}
+
+bool LocalFile::Open() {
+  internal_file_ =
+      base::OpenFile(base::FilePath(file_name()), file_mode_.c_str());
+  return (internal_file_ != NULL);
+}
+
 }  // namespace media

media/file/local_file.h

@@ -3,8 +3,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file or at
 // https://developers.google.com/open-source/licenses/bsd
-//
-// Implements LocalFile.
 
 #ifndef PACKAGER_FILE_LOCAL_FILE_H_
 #define PACKAGER_FILE_LOCAL_FILE_H_
@@ -17,19 +15,27 @@
 
 namespace media {
 
+/// Implement LocalFile which deals with local storage.
 class LocalFile : public File {
  public:
-  LocalFile(const char* name, const char* mode);
+  /// @param file_name C string containing the name of the file to be accessed.
+  /// @param mode C string containing a file access mode, refer to fopen for
+  ///        the available modes.
+  LocalFile(const char* file_name, const char* mode);
 
-  // File implementations.
+  /// @name File implementation overrides.
+  /// @{
   virtual bool Close() OVERRIDE;
   virtual int64 Read(void* buffer, uint64 length) OVERRIDE;
   virtual int64 Write(const void* buffer, uint64 length) OVERRIDE;
   virtual int64 Size() OVERRIDE;
   virtual bool Flush() OVERRIDE;
   virtual bool Eof() OVERRIDE;
+  /// @}
 
  protected:
+  ~LocalFile();
+
   virtual bool Open() OVERRIDE;
 
  private: