Merge pull request #9305 from davidsaada/david_littlefs_fatfs_doxy_fix

Minor Doxygen fixes for all file system classes

Author: 0xc0170

features/storage/filesystem/FileSystem.h

@@ -26,19 +26,19 @@
 #include "BlockDevice.h"
 
 namespace mbed {
-/** \addtogroup filesystem */
+/** \addtogroup file system */
 /** @{*/
 
 
-// Opaque pointer representing files and directories
+// Opaque pointer representing files and directories.
 typedef void *fs_file_t;
 typedef void *fs_dir_t;
 
-// Predeclared classes
+// Predeclared classes.
 class Dir;
 class File;
 
-/** A filesystem object provides filesystem operations and file operations
+/** A file system object. Provides file system operations and file operations
  *  for the File and Dir classes on a block device.
  *
  *  Implementations must provide at minimum file operations and mount
@@ -49,174 +49,174 @@ class File;
 class FileSystem : public FileSystemLike {
 public:
 
-    /** FileSystem lifetime
+    /** File system lifetime.
      *
-     *  @param name       Name to add filesystem to tree as
+     *  @param name       Name to add file system to tree as.
      */
     FileSystem(const char *name = NULL);
     virtual ~FileSystem() {}
 
-    /** Return the default filesystem
+    /** Return the default file system.
      *
-     * Returns the default FileSystem base on the default BlockDevice configuration.
+     * Returns the default file system based on the default block device configuration.
      * Use the components in target.json or application config to change
      * the default block device and affect the default filesystem.
      * SD block device => FAT filesystem
-     * SPIF block device => LITTLE filesystem
-     * DATAFLASH block device => LITTLE filesystem
+     * QSPIF, SPIF, DATAFLASH or FLAHIAP block device => LITTLE filesystem
      *
      * An application can override all target settings by implementing
-     * FileSystem::get_default_instance() themselves - the default
+     * FileSystem::get_default_instance() - the default
      * definition is weak, and calls get_target_default_instance().
      */
     static FileSystem *get_default_instance();
 
-    /** Mounts a filesystem to a block device
+    /** Mount a file system to a block device.
      *
-     *  @param bd       BlockDevice to mount to
-     *  @return         0 on success, negative error code on failure
+     *  @param bd       Block device to mount to.
+     *  @return         0 on success, negative error code on failure.
      */
     virtual int mount(BlockDevice *bd) = 0;
 
-    /** Unmounts a filesystem from the underlying block device
+    /** Unmount a file system from the underlying block device.
      *
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success, negative error code on failure.
      */
     virtual int unmount() = 0;
 
-    /** Reformats a filesystem, results in an empty and mounted filesystem
+    /** Reformat a file system. Results in an empty and mounted file system.
      *
-     *  @param bd       BlockDevice to reformat and mount. If NULL, the mounted
-     *                  block device will be used.
-     *                  Note: if mount fails, bd must be provided.
+     *  @param bd       Block device to reformat and mount. If NULL, the mounted
+     *                  Block device is used.
+     *                  Note: If mount fails, bd must be provided.
      *                  Default: NULL
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success, negative error code on failure.
      */
     virtual int reformat(BlockDevice *bd = NULL);
 
-    /** Remove a file from the filesystem.
+    /** Remove a file from the file system.
      *
      *  @param path     The name of the file to remove.
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success, negative error code on failure.
      */
     virtual int remove(const char *path);
 
-    /** Rename a file in the filesystem.
+    /** Rename a file in the file system.
      *
-     *  @param path     The name of the file to rename.
-     *  @param newpath  The name to rename it to
-     *  @return         0 on success, negative error code on failure
+     *  @param path     The existing name of the file to rename.
+     *  @param newpath  The new name of the file.
+     *  @return         0 on success, negative error code on failure.
      */
     virtual int rename(const char *path, const char *newpath);
 
-    /** Store information about the file in a stat structure
+    /** Store information about the file in a stat structure.
      *
-     *  @param path     The name of the file to find information about
-     *  @param st       The stat buffer to write to
-     *  @return         0 on success, negative error code on failure
+     *  @param path     The name of the file to find information about.
+     *  @param st       The stat buffer to write to.
+     *  @return         0 on success, negative error code on failure.
      */
     virtual int stat(const char *path, struct stat *st);
 
-    /** Create a directory in the filesystem.
+    /** Create a directory in the file system.
      *
      *  @param path     The name of the directory to create.
-     *  @param mode     The permissions with which to create the directory
-     *  @return         0 on success, negative error code on failure
+     *  @param mode     The permissions with which to create the directory.
+     *  @return         0 on success, negative error code on failure.
      */
     virtual int mkdir(const char *path, mode_t mode);
 
-    /** Store information about the mounted filesystem in a statvfs structure
+    /** Store information about the mounted file system in a statvfs structure.
      *
-     *  @param path     The name of the file to find information about
-     *  @param buf      The stat buffer to write to
-     *  @return         0 on success, negative error code on failure
+     *  @param path     The name of the file to find information about.
+     *  @param buf      The stat buffer to write to.
+     *  @return         0 on success, negative error code on failure.
      */
     virtual int statvfs(const char *path, struct statvfs *buf);
 
 protected:
     friend class File;
     friend class Dir;
 
-    /** Open a file on the filesystem
+#if !(DOXYGEN_ONLY)
+    /** Open a file on the file system.
      *
-     *  @param file     Destination for the handle to a newly created file
-     *  @param path     The name of the file to open
-     *  @param flags    The flags to open the file in, one of O_RDONLY, O_WRONLY, O_RDWR,
-     *                  bitwise or'd with one of O_CREAT, O_TRUNC, O_APPEND
-     *  @return         0 on success, negative error code on failure
+     *  @param file     Destination of the newly created handle to the referenced file.
+     *  @param path     The name of the file to open.
+     *  @param flags    The flags that trigger opening of the file. These flags are O_RDONLY, O_WRONLY, and O_RDWR,
+     *                  with an O_CREAT, O_TRUNC, or O_APPEND bitwise OR operator.
+     *  @return         0 on success, negative error code on failure.
      */
     virtual int file_open(fs_file_t *file, const char *path, int flags) = 0;
 
-    /** Close a file
+    /** Close a file.
      *
-     *  @param file     File handle
-     *  @return         0 on success, negative error code on failure
+     *  @param file     File handle.
+     *  return          0 on success, negative error code on failure.
      */
     virtual int file_close(fs_file_t file) = 0;
 
-    /** Read the contents of a file into a buffer
+    /** Read the contents of a file into a buffer.
      *
-     *  @param file     File handle
-     *  @param buffer   The buffer to read in to
-     *  @param size     The number of bytes to read
-     *  @return         The number of bytes read, 0 at end of file, negative error on failure
+     *  @param file     File handle.
+     *  @param buffer   The buffer to read in to.
+     *  @param size     The number of bytes to read.
+     *  @return         The number of bytes read, 0 at the end of the file, negative error on failure.
      */
     virtual ssize_t file_read(fs_file_t file, void *buffer, size_t size) = 0;
 
-    /** Write the contents of a buffer to a file
+    /** Write the contents of a buffer to a file.
      *
-     *  @param file     File handle
-     *  @param buffer   The buffer to write from
-     *  @param size     The number of bytes to write
-     *  @return         The number of bytes written, negative error on failure
+     *  @param file     File handle.
+     *  @param buffer   The buffer to write from.
+     *  @param size     The number of bytes to write.
+     *  @return         The number of bytes written, negative error on failure.
      */
     virtual ssize_t file_write(fs_file_t file, const void *buffer, size_t size) = 0;
 
-    /** Flush any buffers associated with the file
+    /** Flush any buffers associated with the file.
      *
-     *  @param file     File handle
-     *  @return         0 on success, negative error code on failure
+     *  @param file     File handle.
+     *  @return         0 on success, negative error code on failure.
      */
     virtual int file_sync(fs_file_t file);
 
-    /** Check if the file in an interactive terminal device
-     *  If so, line buffered behaviour is used by default
+    /** Check whether the file is an interactive terminal device.
+     *  If so, line buffered behavior is used by default.
      *
-     *  @param file     File handle
-     *  @return         True if the file is a terminal
+     *  @param file     File handle.
+     *  @return         True if the file is a terminal.
      */
     virtual int file_isatty(fs_file_t file);
 
-    /** Move the file position to a given offset from from a given location
+    /** Move the file position to a given offset from a given location.
      *
-     *  @param file     File handle
-     *  @param offset   The offset from whence to move to
-     *  @param whence   The start of where to seek
-     *      SEEK_SET to start from beginning of file,
-     *      SEEK_CUR to start from current position in file,
-     *      SEEK_END to start from end of file
+     *  @param file     File handle.
+     *  @param offset   The offset from whence to move to.
+     *  @param whence   The start of where to seek.
+     *      SEEK_SET to start from the beginning of the file,
+     *      SEEK_CUR to start from the current position in the file,
+     *      SEEK_END to start from the end of the file.
      *  @return         The new offset of the file
      */
     virtual off_t file_seek(fs_file_t file, off_t offset, int whence) = 0;
 
-    /** Get the file position of the file
+    /** Get the file position of the file.
      *
-     *  @param file     File handle
-     *  @return         The current offset in the file
+     *  @param file     File handle.
+     *  @return         The current offset in the file.
      */
     virtual off_t file_tell(fs_file_t file);
 
-    /** Rewind the file position to the beginning of the file
+    /** Rewind the file position to the beginning of the file.
      *
-     *  @param file     File handle
+     *  @param file     File handle.
      *  @note This is equivalent to file_seek(file, 0, FS_SEEK_SET)
      */
     virtual void file_rewind(fs_file_t file);
 
-    /** Get the size of the file
+    /** Get the size of the file.
      *
-     *  @param file     File handle
-     *  @return         Size of the file in bytes
+     *  @param file     File handle.
+     *  @return         Size of the file in bytes.
      */
     virtual off_t file_size(fs_file_t file);
 
@@ -226,66 +226,67 @@ class FileSystem : public FileSystemLike {
      * not changed. If the file is extended, the extended area appears as if
      * it were zero-filled.
      *
-     *  @param file     File handle
-     *  @param length   The requested new length for the file
+     *  @param file     File handle.
+     *  @param length   The requested new length for the file.
      *
-     *  @return         Zero on success, negative error code on failure
+     *  @return         0 on success, negative error code on failure.
      */
     virtual int file_truncate(fs_file_t file, off_t length);
 
-    /** Open a directory on the filesystem
+    /** Open a directory on the file system.
      *
-     *  @param dir      Destination for the handle to the directory
-     *  @param path     Name of the directory to open
-     *  @return         0 on success, negative error code on failure
+     *  @param dir      Destination for the handle to the directory.
+     *  @param path     Name of the directory to open.
+     *  @return         0 on success, negative error code on failure.
      */
     virtual int dir_open(fs_dir_t *dir, const char *path);
 
-    /** Close a directory
+    /** Close a directory.
      *
-     *  @param dir      Dir handle
-     *  @return         0 on success, negative error code on failure
+     *  @param dir      Dir handle.
+     *  @return         0 on success, negative error code on failure.
      */
     virtual int dir_close(fs_dir_t dir);
 
-    /** Read the next directory entry
+    /** Read the next directory entry.
      *
-     *  @param dir      Dir handle
-     *  @param ent      The directory entry to fill out
-     *  @return         1 on reading a filename, 0 at end of directory, negative error on failure
+     *  @param dir      Dir handle.
+     *  @param ent      The directory entry to fill out.
+     *  @return         1 on reading a filename, 0 at the end of the directory, negative error on failure.
      */
     virtual ssize_t dir_read(fs_dir_t dir, struct dirent *ent);
 
-    /** Set the current position of the directory
+    /** Set the current position of the directory.
      *
-     *  @param dir      Dir handle
+     *  @param dir      Dir handle.
      *  @param offset   Offset of the location to seek to,
-     *                  must be a value returned from dir_tell
+     *                  must be a value returned from dir_tell.
      */
     virtual void dir_seek(fs_dir_t dir, off_t offset);
 
-    /** Get the current position of the directory
+    /** Get the current position of the directory.
      *
-     *  @param dir      Dir handle
-     *  @return         Position of the directory that can be passed to dir_rewind
+     *  @param dir      Dir handle.
+     *  @return         Directory position, which can be passed to dir_rewind.
      */
     virtual off_t dir_tell(fs_dir_t dir);
 
-    /** Rewind the current position to the beginning of the directory
+    /** Rewind the current position to the beginning of the directory.
      *
-     *  @param dir      Dir handle
+     *  @param dir      Dir handle.
      */
     virtual void dir_rewind(fs_dir_t dir);
 
-    /** Get the sizeof the directory
+    /** Get the size of the directory.
      *
-     *  @param dir      Dir handle
-     *  @return         Number of files in the directory
+     *  @param dir      Dir handle.
+     *  @return         Number of files in the directory.
      */
     virtual size_t dir_size(fs_dir_t dir);
+#endif //!defined(DOXYGEN_ONLY)
 
 protected:
-    // Hooks for FileSystemHandle
+    // Hooks for file systemHandle
     virtual int open(FileHandle **file, const char *path, int flags);
     virtual int open(DirHandle **dir, const char *path);
 };